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Introduction 



1.1 Overview 

This manual explains how to use the functions given in the C language libraries 
of the XENIX system. In particular, it describes the functions of two C language 
libraries: the standard C library, and the screen updating and cursor 
movement library curse e. 

The C library functions may be called by any program that needs the resources 
of the XENIX system to perform a task. The functions let programs read and 
write to files in the XENIX file system, read and write to devices such as 
terminals and lineprinters, load and execute other programs, receive and 
process signals, communicate with other programs through pipes, share system 
resources, and process errors. 



1.2 Using the C Library Functions 

To use the C library functions you must include the proper function call and 
definitions in the program and specify the corresponding library is given when 
the program is compiled. The standard C library, contained in the file libe.a, is 
automatically specified when you compile a C language program. Other 
libraries, including the screen updating and cursor movement library 
contained in the file libcursee.a, must be explicitly specified when you compile a 
program with the -1 option of the cc command (see Chapter 2, "Cc: a C 
Compiler" in the XENIX Programmer's Guide). 



1.3 Using This Manual 

This manual is intended to be used in conjunction with section S of the XENIX 
Reference Manual. If you have never used the C library functions before, read 
this manual first, then refer to the Reference Manual to learn about other 
functions. If you are familiar with the library functions, turn to the Reference 
Manual to see how these functions may differ from the ones you already know, 
then return to this manual for examples of the functions. 

Chapter 1 introduces the C language libraries. 

Chapter 2 describes the standard input and output functions. These function 
let a program read and write to the files of a XENIX file system. 

Chapter 3 describes the screen processing functions. These functions let a 
program use the screen processing facilities of a user's terminal. 

Chapter 4 describes the character and string processing functions. These 
functions let a program assign, manipulate, and compare characters and 
strings. 
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Using the Standard I/O Functions 

2.1 Introduction 

Nearly all programs use some form of input and output. Some programs read from or 
write to files stored on disk. Others write to devices such as line printers. Many 
programs read from and write to the user's terminal. For this reason, the standard C 
library provides several predefined input and output functions that a programmer can 
useinprograms. 

This chapter explains how to use the I/O functions in the standard C library. In 
particular, it describes: 

— Command line arguments 

— Standard input and output files 

. — Stream functions for ordinary files 

— Low— level functions for ordinary files 

— Random access functions 

2.1.1 Preparing for the I/O Functions 

To use the standard I/O functions a program must include the file stdio.h, which 
defines the needed macros and variables. To include this file, place the following line 
at the beginning of the program . 

#inchide <stdio.h> 

The actual functions are contained in the library file libc.a . This file is automatically 
read whenever you compile a program, so no special argument is needed when you 
invoke the compiler . 

2.1.2 Special Names 

The standard I/O library uses many names for special purposes. In general, these 
names can beusedinany program that has included the stdio.hf&e. 
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main (argc, argv) 
int argc; 
char *argv[]; 

at the beginning of the main program function. When a program begins 
execution, "argc" contains the count, and each element in "argv" contains a 
pointer to one argument. 

An argument is stored as a null- terminated string (i.e., a string ending with a 
null character, \0). The first string (at "argv[0j") is the program name. The 
argument count is never less than 1, since the program name is always 
considered the first argument. 

In the following example, command line arguments are read and then echoed on 
the terminal screen. This program is similar to the XENIX echo command. 

main(argc, argv) /* echo arguments */ 
int argc; 
char *argv[]; 

{ 

int i; 



} 



for (i = 1; i < argc; i++) 

printf("%s%c", argv[ij, (i<argc-l) ? " : '\n'); 



In the example above, an extra space character is added at the end of each 
argument to separate it from the next argument. This is required, since the 
system automatically removes leading and trailing whitespace characters (i.e., 
spaces and tabs) when it reads the arguments from the command line. Adding a 
newline character to the last argument is for convenience only; it causes the 
shell prompt to appear on the next line after the program terminates. 

When typing arguments on a command line, make sure each argument is 
separated from the others by one or more whitespace characters. If an 
argument must contain whitespace characters, enclose that argument in 
double quotation marks. For example, in the command line 

display 3 4 "echo hello" 

the string "echo hello" is treated as a single argument Also enclose in double 
quotation marks any argument that contains characters recognized by the shell 
(e.g., <,>,|,and A ). 

You should not change the values of the "argc" and "argv" variables. If 
necessary, assign the argument value to another variable and change that 
variable instead. You can give other functions in the program access to the 
arguments by assigning their values to external variables. 
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readn (p, cnt) 
char p[]; 
int cnt; 

{ 

int i,c; 



} 



i = 0; 

while ( i<cnt ) 

if ( p[i++] - getcharO) != EOF ) { 
p[i] = 0; 
return(EOF); 

} 

return(O); 



Note that if getehar is reading from the keyboard, it waits for characters to be 
typed before returning. 

The gete function reads a string of characters from the standard input and 
copies the string to a given memory location. The function call has the form: 

gets(e) 

where e is a pointer to the location to receive the string. The function reads 
characters until it finds a newline character, then replaces the newline 
character with a null character (\0) and copies the resulting string to memory. 
The function returns the null pointer value NULL if the end of the file or an 
error is encountered. Otherwise, it returns the value of e. 

The function is typically used to read a full line from the standard input. For 
example, the following program fragment reads aline from the standard input, 
stores it in the character array "cmdln" and calls a function (called pane) if no 
error occurs. 

char cmdln[SIZE]; 

if ( gets(cmdln) !— NULL ) 
parse(); 

In this case, the length of the string is assumed to be less than "SIZE". 

Note that gete cannot check the length of the string it reads, so overflow can 
occur. 

The ecartf function reads one or more values from the standard input where a 
value may be a character string or a decimal, octal, or hexadecimal number. 
The function call has the form: 

scanf (format, argptr ...) 
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You may use the getekar, gets, and ecanf functions in a single program. Just 
remember that each function reads the next available character, making that 
character unavailable to the other functions. 

Note that when the standard input is the terminal keyboard, the getehar, gete, 
and ecanf functions usually do not return a value until at least one newline 
character has been typed. This is true even if only one character is desired. If 
you wish to have immediate input on a single keystroke, see the example in the 
section "Using the system Call" in Chapter 3. 



2.3.2 Writing to the Standard Output 

You can write to the standard output with the putehar, puts, and print/ 
functions. 

The putehar function writes a single character to the output buffer. The 
function call has the form: 

putehar (c) 

where c is the character to be written. The function normally returns the same 
character it wrote, but will return the value EOF if an error is encountered. 

The function is typically used in a conditional loop to write a string of 
characters to the standard output. For example, the function 

writen (p,cnt) 
char p[); 
int cnt; 

{ 

int i; 



} 



for (i=0; i<=cnt; i++) 

putchar( (i !— cnt) ? p[i] : '\n'); 



writes "cnt" number of characters plus a newline character to the standard 
output. 

The puts function copies the string found at a given memory location to the 
standard output. The function call has the form: 

puts(e) 

where e is a pointer to the location containing the string. The string may be any 
number of characters, but must end with a null character (\0). The function 
writes each character in the string to the standard output and replaces the null 
character at the end of the string with a newline character. 
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You may use the putchar, puts, and printf functions in a single program. Just 
remember that the output appears in the same order as it is written to the 
standard output. 



2.3.3 Redirecting the Standard Input 

You can change the standard input from the terminal keyboard to an ordinary 
file by using the normal shell redirection symbol, <. This symbol directs the 
shell to open for reading the file whose name immediately follows the symbol. 
For example, the following command line opens the file phonelist as the 
standard input to the program dial. 

dial < phonelist 

The dial program may then use the getehar, gets, and sc anf functions to read 
characters and values from this file. Note that if the file does notexist, the shell 
displays an error message and stops the program. 

Whenever getehar, gets, or ecan.fa.re used to read from an ordinary file, they 
return the value EOF if the end of the file or an error is encountered. It is useful 
to check for this value to make sure you do not continue to read characters after 
an error has occurred. 



2.3.4 Redirecting the Standard Output 

You can change the standard output of a program from the terminal screen to 
an ordinary file by using the shell redirection symbol, >. The symbol directs 
the shell to open for writing the file whose name immediately follows the 
symbol. For example, the command line 

dial >savephone 

opens the file savephone as the standard output of the program dial and not the 
' terminal screen. You may use the putchar, puts, and printf functions to write 
to the file. 

If the file does not exist, the shell automatically creates it. If the file exists, but 
the program does not have permission to change or alter the file, the shell 
displays an error message and does not execute the program. 



2.3.5 Piping the Standard Input and Output 

Another way to redefine the standard input and output is to create a pipe. A 
pipe simply connects the standard output of one program to the standard input 
of another. The programs may then use the standard input and output to pass 
information from one to the other. You can create a pipe by using the standard 
shell pipe symbol, |. 
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cat filel file2 file3 | ccstrip 



If you wish to save the stripped files, you can redirect the standard output of 
ccetrip. For example, this command line writes the stripped files to the file 
clean. 

cat filel file2 file3 | ccstrip > clean 

Note that the exit function is used at the end of the program to ensure that any 
program which executes the eeetrip program will receive a normal termination 
status (typically 0) from the program when it completes. An explanation of the 
exit function and how to execute one program under control of another is given 
in Chapter 5. 



2.4 Using the Stream Functions 

The functions described so far have all read from the standard input and 
written to the standard output. The next step is to show functions that access 
files not already connected to the program. One set of standard I/O functions 
allows a program to open and access ordinary files as if they were a "stream" of 
characters. For this reason, the functions are called the stream functions. 

Unlike the standard input and output files, a file to be accessed by a stream 
function must be explicitly opened with the fopen function. The function can 
open a file for reading, writing, or appending. A program can read from a file 
with the getc,/getc , fgete, fgetw, /read, and /»c<m/functions. It can write to a 
file with the putc , fputc , fpute, fputw, /write , and fprintf functions. A program 
can test for the end of the file or for an error with the /eo/and /error functions. 
A program can close a file with the /cloee function. 



2.4.1 Using File Pointers 

Every file opened for access by the stream functions has a unique pointer 
associated with it called a file pointer. This pointer, defined with the predefined 
type FILE found in the etdio.h file, points to a structure that contains 
information about the file, such as the location of the buffer (the intermediate 
storage area between the actual file and the program), the current character 
position in the buffer, and whether the file is being read or written. The pointer 
can be given a valid pointer value with the /open function as described in the 
next section. (The NULL value, like FILE, is defined in the etdio.h file. ) 
Thereafter, the file pointer may be used to refer to that file until the file is 
explicitly closed with the /cloee function. 

Typically, a file pointer is defined with the statement: 

FILE *infile; 
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2.4.3 Reading a Single Character 

The getc and fgete functions return a single character read from a given file, 
and return the value EOF if the end of the file or an error is encountered. The 
function calls have the form: 

c «b getc (stream) 

and 

e = fgetc (stream) 

where stream is the file pointer to the file to be read and e is the variable to 
receive the character. The return value is always an integer. 

The functions are typically used in conditional loops to read a string of 
characters from a file. For example, the following program fragment continues 
to read characters from the file given to it by "infile" until the end of the file or 
an error is encountered. 

int i; 

char buf[MAX]; 

FILE*infile; 

while ((c=getc(infile)) !— EOF) 
buf[i++]=c; 

The only difference between the functions is that getc is defined as a macro, and 
fgetc as a true function. This means that, unlike getc, fgetc may be passed as 
an argument in another function, used as a target for a breakpoint when 
debugging, or used to avoid any side effects of macro processing. 



2.4.4 Reading a String from a File 

The fgets function reads a string of characters a file and copies the string to a 
given memory location. The function call has the form: 

fgets (s,n,stream) 

where s is be a pointer to the location to receive the string, n is a count of the 
maximum number of characters to be in the string, and stream is the file 
pointer of the file to be read. The function reads n-1 characters or upto to the 
first newline character, whichever occurs first. The function appends a null 
character (\0j to the last character read and then stores the string at the 
specified location. The function returns the null pointer value NULL if the end 
of the file or an error is encountered. Otherwise, it returnsthe pointer *. 
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function reads from the standard input. The function call has the form: 

fscanf {stream, format, argptr ...) 

where stream is the file pointer of the file to be read, format is a pointer to the 
string that defines the format of the input to be read, and argptr is one or more 
pointers to the variables that are to receive the formatted input. There must be 
one argptr for each format given in the format string. The format may be "%s" 
for a string, "%c" for a character, and "%d", "%o", or "%x" for a decimal, 
octal, or hexadecimal number, respectively. (Other formats are described in 
seanf{S) in the XENIX Reference Manual.) The function normally returns the 
number of arguments it read, but will return the value EOF if the end of the file 
or an error is encountered. 

The function is typically used to read files that contain both numbers and text. 
For example, this program fragment reads a name and a decimal number from 
the file given by "file". 

FILE *file; 

int pay; 

char name [20]; 

fscanf (file," %s %d\n", name, &pay); 

This program fragment copies the name to the character array "name" and the 
number to the integer variable "pay". 

2.4.7 Writing a Single Character 

The pute and fpute functions write single characters to a given file. The 
function calls have the forms: 

putc {c,stream) 

and 

fputc (c,stream) 

where c is the character to be written and stre am is the file pointer to the file to 
receive the character. The function normally returns the character written, 
but will return the value EOF if an error is encountered. 

The function is defined as a macro and may have undesirable side effects 
resulting from argument processing. In such cases, the equivalent function 
fpute should be used. 

These functions are typically used in conditional loops to write a string of 
characters to a file. For example, this following program fragment writes 
characters from the array "name" to the file given by "out". 
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2.4.0 Writing Formatted Output 

The /print/ function writes formatted output to a given file, just as the print/ 
function writes to the standard output. The function call has the form: 

fprintf (etre am, format [, arg ]...) 

where etre am is the file pointer of the file to be written to, /ormat is a pointer to 
a string which defines the format of the output, and arg is one or more 
arguments to be written. There must be one arg for each format in the /ormat 
string. The formats may be "%s" for a string, "%c" for a character, and 
"%d", "%o", or "%x" for a decimal, octal, or hexadecimal number, 
respectively. (Other formats are described in print/(S) in the XENIX Re/ercnce 
Manual.) If a string is requested, the corresponding arg must be a pointer, 
otherwise, the actual variable must be used. The function normally returns 
zero, but will return a nonzero number if an error is encountered. 

The function is typically used to write output that contains both numbers and 
text. For example, to write a name and a decimal number to the file given by 
"outfile" use the following program fragment. 

FILE *outfile; 

int pay; 

char name [20]; 

fprintf(outfile," %s %d\n" , name, pay); 

The name is copied from the character array "name" and the number from the 
integer variable "pay". 



2.4.10 Writing Records to a File 

The /write function writes one or more records to a given file. The function call 
has the form: 

fwrite (ptr, size, niteme, etre am) 

where ptr is a pointer to the first record to be written, eize is the size (in bytes) of 
each record, niteme is the number of records to be written, and etream is the file 
pointer of the file. The ptr may point to a variable of any type (from a single 
character to a structure). The eize should give the number of by tes in each item 
to be written. One way to ensure this is to use the eizeo/ function (see the 
example below). The function always returns the number of items actually 
written to the file whether or not the end of the file or an error is encountered. 

The function is typically used to write binary data to a file. For example, the 
following program fragment writes two records to the file given by "database". 
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The function is typically used to test for errors before perform a subsequent 
read or write to the file. For example, in the following program fragment/error 
tests the file given by "stream". 

char *buf; 
char x[5]; 

while ( Iferror(stream) ) 

fread(buf, sizeof(x), 10, stream); 

If it returns zero, the next item in the file given by "stream" is copied to "bur'. 
Otherwise, execution passes to the next statement. 

Further use of a file after a error is detected may cause undesirable results. 



2.4.13 Closing a File 

The fclote function closes a file by breaking the connection between the file 
pointer and the structure created by fopen. Closing a file empties the contents 
of the corresponding buffer and frees the file pointer for use by another file. The 
function call has the form: 

f close {stream) 

where etream is the file pointer of the file to close. The function normally 
returns 0, but will return -1 if an error is encountered. 

The fclote function is typically used to free file pointers when they are no longer 
needed. This is important because usually no more than 20 files can be open at 
the same time. For example, the following program fragment closes the file 
given by "infile" when the file has reached its end. 

FILE *infile; 

if ( feof(infile) ) 

fclose( infile ); 

Note that whenever a program terminates normally, the fclote function is 
automatically called for each open file, so no explicit call is required unless the 
program must close a file before its end. Also, the function automatically calls 
fflueh to ensure that everything written to the file's buffer actually gets to the 
file. 



2.4.14 Program Example 

This section shows how you may use the stream functions you have seen so far 
to perform useful tasks. The following program, which counts the characters, 
words, and lines found in one or more files, uses the /open, fprintf, gete, and 
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#include <stdio.h> 



main(argc, argv) /* wc: count lines, words, chars */ 
int argc; 
char *argvfl; 

int c, i, inword; 

FILE *fp, *fopen(); 

long linect, wordct, charct; 

long tlinect = 0, twordct = 0, tcharct = 0; 

i=l; 

fp = stdin; 
do 

{ 

if (argc > 1 && 

(fp=fopen(argv[i], "r")) == NULL) { 
fprintf (stderr, "wc: can't open %s\n", 

argv[i]); 
continue; 

> 

linect s=b wordct = charct = inword = 0; 

while ((c — getc(fp)) != EOF) { 

charct++; 

if(c==V) 

linect++; 
if (c ."He '\t' || c -- V) 

inword = 0; 
else if (inword == 0) { 

inword = 1; 

wordct++; 

} 
} 

printf("%71d %71d %71d", linect, wordct, charct); 
printffargc > 1 ? " %s\n" : ^n", argv[i]); 
fclose(fp); 
tlinect += linect; 
twordct += wordct; 
tcharct +== charct; 
} while (++i < argc); 
if (argc > 2) 

printf( B %71d %71d %71d total\n", tlinect, 
twordct, tcharct); 
exit(0); 
} 

The program uses "fp" as the pointer to receive the current file pointer. 
Initially this is set to "stdin" in case no filenames are present in the command 
line. If a filename is present, the program calls/open and assigns the file pointer 
to "fp". If the file cannot be opened (in which case /open returns NULL), the 
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and the ffluek function lets a program flush the buffer before it is full. 

2.5.2 Reopening a File 

The f re open closes the file associated with a given file pointer, then opens anew 
file and gives it the same file pointer as the old file. The function call has the 
form: 

freopen (newfile, type, etream) 

where newfile is a pointer to the name of the new file, type is a pointer to the 
string that defines how the file is to be opened ("r" for read, "w" for writing, 
and "a" for appending), and etream is the file pointer of the old file. The 
function returns the file pointer etre am if the new file is opened. Otherwise, it 
returns the null pointer value NULL. 

The freopen function is used chiefly to attach the predefined file pointers 
"stdin", "stdout", and "stderr" to other files. For example, the following 
program fragment opens the file named by "newfile" as the new standard 
output file. 

char *newfile; 
FILE *nfile; 

nfile = freopen(newfile,"r", stdout); 

This has the same effect as using the redirection symbols in the command line of 
the program. 



2.5.3 Setting the Buffer 

The eetbuf function changes the buffer associated with a given file to the 
program's own buffer. It can also change the access to the file to no buffering. 
The function call has the form: 

setbuf [etre am, buf) 

where etre am is a file descriptor and buf is a pointer to the new buffer, or is the 
null pointer value NULL if no buffering is desired. If a buffer is given, it must be 
BSIZE bytes in length, where BSIZE is a manifest constant found in etdio. h. 

The function is typically used to to create a buffer for the standard output when 
it is assigned to the user's terminal, improving execution time by eliminating 
the need to write one character to the screen at a time. For example, the 
following program fragment changes the buffer of the standard output the 
location pointed at by "p". 
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Note that the value EOF must never be put back in the buffer. 

2.5.5 Flushing a File Buffer 

The flluth function empties the buffer of a give file by immediately writing the 
buffer contents to the file. The function call has the form: 

fflush {stream) 

where stream is the file pointer of the file. The function normally returns zero, 
but will return the value EOF if an error is encountered. 

The function is typically used to guarantee that the contents of a partially filled 
buffer are written to the file. For example, the following program fragment 
empties the buffer for the file given by "outtty" if the error condition given by 
"errflag"isO. 

FILE *outtty; 
int errflag; 

if (errflag «-■■ 0) 

fflush( outtty ); 

Note that fflush is automatically called by the /close function to empty the 
buffer before closing the file. This means that no explicit call to flush is 
required if the file is also being closed. 

The function ignores any attempt to empty the buffer of a file opened for 
reading. 



2.8 Using the Low-Level Functions 

The low-level functions provide direct access to files and peripheral devices. 
They are actually direct calls to the routines used in the XENIX operating 
system to read from and write to files and peripheral devices. The low-level 
functions give a program the same control over a file or device as the system, 
letting it access the file or device in ways that the stream functions do not. 
However, low-level functions, unlike stream functions, do not provide buffering 
or any other useful services of the stream functions. This means that any 
program that uses the low-level functions has the complete burden of handling 
input and output. 

The low-level functions, like the stream functions, cannot be used to read from 
or write to a file until the file has been opened. A program may use the open 
function to open an existing or a new file. A file can be opened for reading, 
writing, or appending. 
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int in, out; 



in — open( " /usr /accounts" , OJIDONLY ); 

out = open( "/usr/tmp/scratch", 0_WRONLY | 0_CRFAT, 0754 ); 

In the XENIX system, each file has 9 bits of protection information which 
control read, write, and execute permission for the owner of the file, for the 
owner's group, and for all others. A three-digit octal number is the most 
convenient way to specify the permissions. For example, in the example above 
the octal number "0755" specifies read, write, and execute permission for the 
owner, read and execute permission for the group, and read everyone else. 

Note that if OjCREAT is given and the file already exists, the function destroys 
the file's old contents. 



2.6.3 Reading Bytes From a File 

The re ad function reads one or more bytes of data from a given file and copies 
them to a given memory location. The function call has the form: 

n_read = read(/rf, 6«/, n); 

where n_re ad is the v ariable to receive the count of bytes actually read, /rfis the 
file descriptor of the file, fc«/is a pointer to the memory location to receive the 
, bytes read, and n is a count of the desired number of bytes to be read. The 
function normally returns the same number of bytes as requested, but will 
return fewer if the file does not have that many bytes left to be read. The 
function returns if the file has reached its end, or -1 if an error is encountered. 

When the file is a terminal, read normally reads only up to the nextnewline. 

The number of bytes to be read is arbitrary. The two most common values are 
1, which means one character at a time, and 1024, which corresponds to the 
physical block size on many peripheral devices. 



2.6.4 Writing Bytes to a File 

The write function writes one or more bytes from a given memory location to a 
given file. The function call has the form: 

njwritten = write(/rf, buf, n); 

where n_turtfie n is the variable to receive a count of bytes actually written, /<f is 
the file descriptor of the file, btifis the name of the buffer containing the bytes to 
be written, and n is the number of bytes to be written. 

The function always returns the number of bytes actually Written. It is 
considered an error if the return value is not equal to the number of bytes 
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#define BUFSIZE BSIZE 

main() /* copy input to output */ 

char buf[ BUFSIZE \; 
int n; 



} 



while ((n = read( 0, buf, BUFSIZE )) > 0) 

write(l, buf, n); 
cxit(0); 



The program uses the read function to read BUFSIZE bytes from the standard 
input (file descriptor 0). It then uses write to write the same number of bytes it 
read to the standard output (file descriptor 1). If the standard input file size is 
not a multiple of BUFSIZE, the last read returns asmaller number of bytes to be 
written by write, and the next call to re ad returns zero. 

This program can be used like a copy command to copy the content of one file to 
another. You can do this by redirecting the standard input and output files. 

The second example shows how the read and write functions can be used to 
construct higher level functions like getehar and putckar. For example, the 
following is aversion of getehar which performs unbuffered input: 

# define CMASK 0377 /* for making chars > */ 

getchar()/* unbuffered single character input */ 
{ 

return((read(0, &c, 1) > 0) ? c & CMASK : EOF); 
} 

The variable "c" must be declared char, because read accepts a character 
pointer. In this case, the character being returned must be masked with octal 
0377 to ensure that it is positive; otherwise sign extension may make it 
negative. 

The second version of getehar reads input in large blocks, but hands out the 
characters one at a time: 
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error(sl, s2) /* print error message and die */ 

char *sl, *s2; 

{ 

printf(sl, s2); 

printfi'V); 
exit(l); 

} 

There is a limit (usually 20) to the number of files that a program may have 
open simultaneously. Therefore, any program which intends to process many 
files must be prepared to reuse file descriptors by closing unneeded files. 



2.6.7 Using Random Access I/O 

Input and output operations on any file are normally sequential. This means 
each read or write takes place at the character position immediately after the 
last character read or written. The standard library, however, provides a 
number of stream and low-level functions that allow a program to access a file 
randomly, that is, to exactly specify the position it wishes to read from or write 
to next. 

The functions that provide random access operate on a file's "character 
pointer". Every open file has a character pointer that points to the next 
character to be read from that file, or the next place in the file to receive a 
character. Normally, the character pointer is maintained and controlled by the 
system, but the random access functions let a program move the pointer to any 
position in the file. 



2.6.8 Moving the Character Pointer 

The leeek function, a low-level function, moves the character pointer in a file 
opened for low-level access to a given position. The function call has the form: 

lseek(/rf, offset, origin); 

where fd is the file descriptor of the file, offset is the number of bytes to move the 
character pointer, and origin is the number that gives the starting point for the 
move. It may be for the beginning of the file, 1 for the current position, and 2 
for the end. 

For example, this call forces the current position in the file whose descriptor is 3 
to move to the 512th byte from the beginning of the file. 

lseek( 3, (long)512, ) 

Subsequent reading or writing will begin at that position. Note that offset must 
be a long integer and fd and origin must be integers. 
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The function may be used on either buffered or unbuffered files. 

2.6.10 Rewinding a File 

The rewind function, a stream function, moves the character pointer to the 
beginning of a given file. The function call has the form: 

rewind ($tream) 

where etream is the file pointer of the file. The function is equivalent to the 
following function call 

fseek (stream,0L,0); 

Itis chiefly used as amore readable version of the call. 

2.6.11 Getting the Current Character Position 

The /tell function, a stream function, returns the current position of the 
character pointer in the given file. The returned position is always relative to 
the beginning of the file. The function call has the form: 

p = ftell (etream) 

where etre am is the file pointer of the file and p is the variable to receive the 
position. The return value is always a long integer. The function returns the 
value -1 if an error is encountered. 

The function is typically used to save the current location in the file so that the 
program can later return to that position. For example, the following program 
fragment first saves the current character position in "oldp", then restores the 
file to this position if the current character position is greater than "800". 

FILE *outfile; 
long oldp; 

oldp — ftell( outfile ); 

if ((ftell( outfile )) > 800) 

fseek(outfile, oldp, 0); 

The ftellis identical to the function call 

lseek( fd, (long)0, 1) 

where fd is the file descriptor of the given stream file. 
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Screen Processing 



3.1 Introduction 



This chapter explains how to use the screen updating and cursor movement 
library named cvree$. The library provides functions to create and update 
screen windows, get input from the terminal in a screen-oriented way, and 
optimize the motion of the cursor on the screen. 



3.1.1 Screen Processing Overview 

Screen processing gives a program a simple and efficient way to use the 
capabilities of the terminal attached to the program's standard input and 
output files. Screen processing does not rely on the terminal's type. Instead the 
screen processing functions use the XENIX terminal capability file 
/ete/termcap to tailor their actions for any given terminal. This makes a 
screen processing program terminal-independent. The program can be run 
with any terminal as long as that terminal is described in the / ete/termcap file. 

The screen processing functions access a terminal screen by working through 
intermediate "screens" and "windows" in memory. A screen is a 
representation of what the entire terminal screen should look like. A window is 
a representation of what some portion of the terminal screen should look like. 
A screen can be made up of one or more windows. A window can be as small as a 
single character or as large as an entire screen. 

Before a screen or window can be used, it must be created by using the newroin 
or $ubwi n functions. These functions define the size of the screen or window in 
terms of lines and columns. Each position in a screen or window represents a 
place for a single character and corresponds to a similar place on the terminal 
screen. Positions are numbered according to line and column. For example, the 
position in the upper left corner of a screen or window is numbered (0,0) and the 
position immediately to its right is (0,1). A typical screen has 24 lines and 80 
columns. Its upper left corner corresponds to the upper left corner of the 
terminal screen. A window, on the other hand, may be any size (within the 
limits of the actual screen). Its upper left corner can correspond to any position 
on the terminal screen. For convenience, the initecr function which initializes a 
program for screen processing also creates a default screen , stdecr (for 
"standard screen"). The etdter may be used without first creating it. The 
function also creates eureer (for "current screen") which contains a copy of 
what is currently on the terminal screen. 

To display characters at the terminal screen, a program must write these 
characters to a screen or window using screen processing functions such as 
adieh and waddch. If necessary, a program can move to the desired position in 
the screen or window by using the move and wmove functions. Once characters 
are added to a screen or window, the program can copy the characters to the 
terminal screen by using the refresh or wrefresh function. These functions 
update the terminal screen according to what has changed in the given screen 
or window. Since the terminal screen is not changed until a program calls 
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Variables 



Type 


Name 


Description 


WINDOW* 


curscr 


A pointer to the current version of the 
terminal screen. 


WINDOW* 


stdscr 


A pointer to the default screen used 
for updating when no explicit screen 
is defined. 


char 


Def_term 


A pointer to the default terminal type 
if the type cannot be determined. 


bool 


My_term 


The terminal type flag. If set, it 
causes the terminal specification in 
"Def_term" to be used, regardless of 
the real terminal type. 


char 


ttytype 


A pointer to the full name of the 
current terminal. 


int 


LINES 


The number of lines on the terminal. 


int 


COLS 


The number of columns on the 
terminal. 


int 


ERR 


The error flag. Returned by functions 
on an error. 


int 


OK 


The okay flag. Returned by functions 
on successful operation. 
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3.2.2 Using Terminal Capability and Type 



The inittcr function uses the terminal capability descriptions given in the 
XENIX system's /ete/termeap file to prepare the screen processing functions 
for creating and updating terminal screens. The descriptions define the 
character sequences required to perform a given operation on a given terminal. 
These sequences are used by the screen processing functions to add, insert, 
delete, and move characters on the screen. The descriptions are automatically 
read from the file when screen processing is initialized, so direct access by a 
program is not required. 

The initeer function uses the shell's "TERM" variable to determine which 
terminal capability description to use. The "TERM" variable is usually 
assigned an identifier when a user logs in. This identifier defines the terminal 
type and is associated with a terminal capability description in the 
/ete/termeap file. 

If the "TERM" variable has no value, the functions use the default terminal 
type in the library's predefined variable "Def_term". This variable initially 
has the value "dumb" (for "dumb terminal"), but the user may change it to any 
desired value. This must be done before calling the initeer function. 

In some cases, it is desirable to force the screen processing functions to use the 
default terminal type. This can be done by setting the library's predefined 
variable "My_term" to the value 1. The full name of the current terminal is 
stored in the predefined variable "ttytype". 

Terminal capabilities, types, and identifiers are described in detail in 
termeap(F) in the XENIX f?e/ere nee Manual. 



3.2.3 Using Default Terminal Modes 

The initeer function automatically sets a terminal to default operation modes. 
These modes define how the terminal displays characters sent to the screen and 
how it responds to characters typed at the keyboard. The t"ntf»er function sets 
the terminal to ECHO mode which causes characters typed at the keyboard to 
be displayed at the screen, and RAW mode which causes characters to be used as 
direct input (no editing or signal processing is done). 

The default terminal modes can be changed by using the appropriate functions 
described in the section "Setting a Terminal Mode" in this chapter. If the 
modes are changed, they must be changed immediately after calling initeer. 
Terminal modes are described in detail in tty(M) in the XENIX Reference 
Manual. 
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^include <curses.h> 

main () 
{ 

initscr(); 

/* Program body. */ 
endwin(); 
> 

Note that endwin must not be called if tntfoer has not been called. Also, endwin 
should be called before any call to the exit function. The endwin function must 
also be called if the gettmode and eetterm functions have been called even if 
i filler has not. 



3.3 Using the Standard Screen 

The following sections explain how to use the standard screen to display and 
edit characters on the terminal screen. 



3.3.1 Adding a Character 

The addch function adds a given character to the standard screen and moves 
the character pointer one position to the right. The function call has the form: 

addchf eh) 

where eh gives the character to be added and must have char type. For 
example, if the current position is (0, 0), the function call 

addch('A') 

places the letter "A" at this position and moves the pointer to (0, 1). 

If a newline f\n') character is given, the function deletes all characters from the 
current position to the end of the line and moves the pointer one line down. If 
the newline flag is set, the function deletes the characters and moves the 
pointer to the beginning of the next line. If a return ('\r') is given, the function 
moves the pointer to the beginning of the current line. If a tab ('\t') is given, the 
function moves the pointer to the next tab stop, adding enough spaces to fill the 
gap between the current position and the stop. Tab stops are placed at every 
eight character positions. 

The function returns ERR if it encounters an error, such as illegal scrolling. 
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prints the number "15" immediately after the name. 

The function returns ERR if it encounters an error such as illegal scrolling. 

3.3.4 Reading a Character From the Keyboard 

The geteh function reads a single character from the terminal keyboard and 
returns the character as a value. The function call has the form: 

c = getch() 

where e is the variable to receive the character. 

The function is typically used to read a series of individual characters. For 
example, in the following program fragment, characters are read and stored 
until a newline or the end of the file is encountered, or until the buffer size has 
been reached. 

char c, p[MAX]; 
int i; 

i = 0; 

while ((c=±getch()) != >» && c != EOF && i <MAX ) 
p [i ++ ] - c; 

If the terminal is set to ECHO mode, geteh copies the character to the standard 
screen; otherwise, the screen remains unchanged. If the terminal is not set to 
RAW or NOECHO mode, geteh automatically sets the terminal to CBREAK 
mode, then restores the previous mode after reading the character. Terminal 
modes are described later in the chapter. 

The function returns ERR if it encounters an error such as illegal scrolling. 

3.3.5 Reading a String From the Keyboard 

The getstr function reads a string of characters from the terminal keyboard 
and copies the string to a given location. The function call has the form: 

getstr( etr ) 

where etr is a character pointer to the variable or location to receive the string. 
When typed at the keyboard, the string must end with a newline character or 
with the end-of-file character. The extra character is replaced by a null 
character when the string is stored. It is the programmer's responsibility to 
ensure that str has adequate space to store the typed string. 

The function is typically used to read names and other text from the keyboard. 
For example, in the following program fragment, reads a filename from the 
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3.3.7 Moving the Current Position 



The move function moves the pointer to the given position. The function call 
has the form: 

move (y, x) 

where y is an integer value giving the new row position, and * is an integer value 
giving the new column position. For example, if the current position is (0,0), 
the function call 

move(5,4) 

moves the pointer to line 5, column 4. 

The function returns ERR if it encounters an error such as illegal scrolling. 

3.3.8 Inserting a Character 

The ineck function inserts a character at the current position and shifts the 
existing character (and all characters to its right) one position to the right. The 
function call has the form: 

insch ( c ) 

where c is the character to be inserted. 

The function is typically used to insert a series of characters into an existing 
line. For example, in the following program fragment inechis used to insertthe 
number of characters given by "cnt" into the standard screen a the current 
position. 

int cnt; 
char *string; 

while ( cnt != ) { 

insch(string[cnt]); 

cnt--; 

} 

The function returns ERR if it encounters an error such as illegal scrolling. 

3.3.0 Inserting a Line 

The ineertln function inserts a blank line at the current position and moves the 
existing line (and all lines below it) down one line, causing the last line to move 
ft* the bottom of the screen. The function call has the form: 
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The deleteln function is used to delete existing lines from the standard screen. 
For example, in the following program fragment deleteln is used to delete aline 
from the standard screen if the count in "cnt" is 79. 

int cnt; 

if ( cnt — — 79 ) 

deletelnQ; 



3.3.12 Clearing the Screen 

The dear and erase functions clear all characters from the standard screen by 
replacing them with spaces. The functions are typically used to prepare the 
screen for new text. 

The clear function clears all characters from the standard screen, moves the 
pointer to (0,0), and sets the standard screen's clear flag. The flag causes the 
next call to the refre eh function to clear all characters from the terminal screen. 

The erase function clears the standard screen, but does not set the clear flag. 
For example, in the following program fragment clear clears the screen if the 
input value is 12. 

char c; 

if ((c=getch()) ===== 12) 
clearQ; 



3.3.13 Clearing a Part of the Screen 

The clrtobot and clrtoeol functions clear one or more characters from the 
standard screen by replacing the characters with spaces. The functions are 
typically used to prepare a partof the standard screen for new characters. 

The clrtobot function clears the screen from the current position to the bottom 
of the screen. For example, if the current position is (10,0), the function call 

clrtobot(); 

clears all characters from line 10 and all lines below line 10. 

The clrtoeol function clears the standard screen from the current position to 
the end of the current line. For example, if the current position is (10,10), the 
function call 

clrtoeolQ; 
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where win is the pointer variable to receive the return value, line$ and eolt are 
integer values that give the total number of lines and columns, respectively, in 
the window, and begin jy and begin_x are integer values that give the line and 
column positions, respectively, of the upper left corner of the window when 
displayed on the terminal screen. The win variable must have type 
WINDOW*. 

The function is typically used in programs that maintain a set of windows, 
displaying different windows at different times or alternating between window 
as needed. For example, in the following program fragment newwin creates a 
new window and assigns the pointer to this window to the variable mideereen. 

WINDOW *midscreen; 

midscreen = newwin(5, 10, 8, 35); 

The window has 5 lines and 10 columns. The upper left corner of the window is 
placed at the position (9,35) on the terminal screen. 

If either ftneeor cole is zero, the function automatically creates a window that 
has "LINES - beginjy" lines or "COLS - begin_x" columns, where "LINES" 
and "COLS" are the predefined constants giving the total number of lines and 
columns on the terminal screen. For example, the function call 

newwin(0, 0, 0, 0) 

creates a new window whose upper left corner is at position (0,0) and that has 
"LINES" lines and "COLS" columns. 



Note 



You must not create windows that exceed the dimensions of the actual 
screen. 



The newwin function returns the value (WINDOW*) ERR on an error, such as 
insufficient memory for the new window. 



3.4.2 Creating a Subwindow 

The subwin function creates a subwindow and returns a pointer to the new 
window. A subwindow is a window which shares all or part of the character 
space of another window and provides an alternate way to access the characters 
in that space. The function call has the form: 
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pointer to the given string. For example, if the current position is (0,0), the 
function call 

waddstr(midscreen, "line"); 

places the beginning of the string "line" at this position and moves the pointer 
to (0,4). 

The wprintw function prints one or more values on the given window, where a 
value may be a string, a character, or a decimal, octal, or hexadecimal number. 
The function call has the form: 

wprintw( win, fmt [, arg ] ...) 

where win is a pointer to the window to receive the values, fmt is a pointer to a 
string that defines the format of the values, and arg is a value to be printed. If 
more than one arg is given, each must be separated from the preceding with a 
comma (,). For each arg given, there must be a corresponding format given in 
fmt. A format may be "%s" for string, "%c" for character, and "%d", "%o", 
or "%x" for a decimal, octal, or hexadecimal number, respectively. (Other 
formats are described in printf{S) in the XENIX Reference Manual.) If "%s" is 
given, the corresponding arg must be a character pointer. For other formats, 
the actual value or avariable containing the value may be given. 

The function is typically used to copy both numbers and strings to the standard 
screen at the same time. For example, in the following program fragment 
wprintw prints a name and then the number " 15" at the current position in the 
window "midscreen". 

char *name; 

wprintw(midscreen, "%s %d", name, 15); 

Note that when a newline, return, or tab character is given to a waddch, 
waddstr, or wprintw function, the functions perform the same actions as 
described for the addch function. The functions return ERR if they encounter 
errors such as illegal scrolling. 



3.4.4 Reading and Scanning for Input 

The wgetch, wgetetr, and wecanw functions read characters, strings, and 
numbers from the standard input file and usually echo the values by copying 
them to the given window. 

The wgete h function reads a single character from the standard input file and 
returns the character as a value. The function call has the form: 

c sas wgetch( win ) 
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The function is typically used to read a combination of strings and numbers 
from the keyboard. For example, in the following program fragment wicanw 
reads a name and a number from the keyboard. 

char name[20]; 
int id; 

wscanw(midscreen, "%s %d", name, &id); 

In this example, the name is stored in the character array "name" and the 
number in the integer variable "id". . 

If the terminal is set to ECHO mode, the function copies the string to the given 
window. If the terminal is not set to RAW or NOECHO mode, the function 
automatically sets the terminal to CBREAK mode, then restores the previous 
mode after reading the character. 

The functions return ERR if they encounter errors such as illegal scrolling. 



3.4.5 Moving a the Current Position in a Window 

The wmove function moves the current position in a given window. The 
function call has the form: 

wmove (tpt'n, y, x) 

where win is a pointer to a window, y is an integer value giving the new line 
position, and x is an integer value giving the new column position. For example, 
the function call 

wmove(midscreen, 4, 4) 

moves the current position in the window "midscreen" to (4,4). 

The function returns ERR if it encounters an error such as illegal scrolling. 

3.4.6 Inserting Characters 

The winseh and winsertln functions insert characters and lines into a given 
window. 

The wintch function inserts a character at the current position and shifts the 
existing character (and all characters to its right) one position to the right. The 
function call has the form: 

winseh ( win, c) 

where win is a pointer to a window, and e is the character to be inserted. 
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The wdeleteln function deletes the current line and shifts the line below the 
deleted line (and all lines below it) one line up, leaving the last line in the screen 
blank. The function call has the form: 

wdeleteln( win ) 

where win is a pointer to a window. 

The function is typically used to delete existing lines from a given window. For 
example, in the following program fragment wdeleteln deletes the lines in 
"midscreen" until "cnt" is equal to zero. 

int cnt; 

while ( cnt !== ) { 

wdeleteln(midscreen); 

cnt--; 

} 



3.4.8 Clearing the Screen 

The welear, weraee, wclrtobot, and wclrtoeol functions clear all or part of the 
characters from the given window by replacing them with spaces. The 
functions are typically used to prepare the window for new text. 

The welear function clears all characters from the window, moves the pointer 
to (0,0), and sets the standard screen's clear flag. The flag causes the next 
refresh function call to clear all characters from the terminal screen. The 
function call has the form: 

welear ( win ) 

where win is the window to be cleared. 

The weraee function clears the given window, moves the pointer to (0,0), but 
does not set the clear flag. It is used whenever the contents of the terminal 
screen must be preserved. The function call has the form: 

werase( win ) 

where win is a pointer to the window to be cleared. 

The wclrtobot function clears the window from the current position to the 
bottom of the screen. The function call has the form: 

wclrtobot( win ) 

where win is a pointer to the window to be cleared. For example, if the current 
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Note 



If eurecr is given with vorefreeh, the function restores the actual screen 
to its most recent contents. This is useful for implementing a 
"redraw" feature for screens that become cluttered with unwanted 
output. 



The function returns ERR if it encounters an error such as illegal scrolling. If an 
error is encountered, the function attempts to update as much of the screen as 
possible without causing the scroll. 



3.4.10 Overlaying Windows 

The overlay function copies all characters, except spaces, from one window to 
another, moving characters from their original positions in the first window to 
identical positions in the second. The function effectively lays the first window 
over the second, letting characters in the second window that would otherwise 
be covered by spaces remain unchanged. The function call has the form: 

overlay( winl, winS) 

where winl is a pointer to the window to be copied, and winS'vs a pointer to the 
window to receive the copied text. The starting positions of winl and ipinS 
must match, otherwise an error occurs. If winlis larger than wing, the function 
copies only those lines and columns in winl that fit in winS. 

The function is typically used to build a composite screen from overlapping 
windows. For example, in the following program fragment overlay is used to 
build the standard screen from two different windows. 

WINDOW *info, *cmdmenu; 

overlay(info, stdscr); 
overlay(cmdmenu, stdscr); 
refreshQ; 



3.4.11 Overwriting a Screen 

The overwrite function copies all characters, including spaces, from one 
window to another, moving characters from their positions in the first window 
to identical positions in the second. The function effectively writes the contents 
of the first window over the second, destroying the previous contents of the 
second window. The function call has the form: 
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c = inchQ 

where c is the character variable to receive the character read. 

The winch function reads a character from a given window or screen. The 
function call has the form: 

c ■» winch( win ) 

where win is the pointer to the window containing the character to be read. 

The functions are typically used to compare the actual contents of a window 
with what is assumed to be there. For example, in the following program 
fragment inch and wine A are used to compare the characters at position (0,0) in 
the standard screen and in the window named "altscreen". 

char cl, c2; 

cl = inchQ; 

c2 = winch(altscreen); 

if (cl != c2 ) 

errorQ; 

Note that reading a character from a window does not alter the contents of the 
window. 

3.4.14 Touching a Window 

The touehwin function makes the entire contents of a given window appear to 
be modified, causing a subsequent refreeh call to copy all characters in the 
window to the terminal screen. The function call has the form: 

touchwin( twn ) 

where win is a pointer to the window to be touched. 

The function is typically used when two or more overlapping windows make up 
the terminal screen. For example, the function call 

touchwin(leftscreen); 

is used to touch the window named "leftscreen". A subsequent refreek copies 
all characters in "leftscreen" to the terminal screen. 

3.4.15 Deleting a Window 

The delwin function deletes a given window from memory, freeing the space 
previously occupied by the window for other windows or for dynamically 
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The standout function sets the standout attribute for characters added to the 
standard screen. The function call has the form: 

standout() 

No arguments are required. 

The wstandout function sets the standout attribute of characters added to the 
given window or screen. The function call has the form: 

wstandout( win ) 

where win is a pointer to a window. 

The functions are typically used to make error messages or instructions clearly 
visible when displayed at the terminal screen. For example, in the following 
program fragment standout sets the standout character attribute before 
adding an error message to the standard screen. 

if ( code •= 5 ) { 

standoutQ; 

ad dstr(" Illegal character.\n"); 

> " 

Note that the actual appearence of characters with the standout attribute 
depends on the given terminal. This attribute is defined by the SO and SE (or 
US and UE) sequences given in the terminal's te rme op entry (see termcap{M) in 
the XENIX Reference Manual). 

3.5.3 Restoring Normal Characters 

The etandend znd wetandend functions restore the normal character attribute, 
causing characters subsequently added to a given window or screen to be 
displayed as normal characters. 

The etandend function restores the normal attribute for the standard screen. 
The function call has the form: 

standend() 

No arguments are required. 

The wetandend function restores the normal attribute for a given window or 
screen. The function call has the form: 

wstandend( win ) 

where win is a pointer to a window. 
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leaveok( win, state ) 



where win is a pointer to the window containing the flag to be set, and state is a 
Boolean value defining the state of the flag. If etate is TRUE the flag is set; if 
FALSE, the flag is cleared. For example, the function call 

leaveok(stdscr, TRUE); 

sets the cursor flag. 

The serollok function sets or clears the scroll flag for the given window. If the 
flag is set, scrolling through the window is allowed. If the flag is clear, then no 
scrolling is allowed. The function call has the form: 

scrollok( win, state ) 

where win is a pointer to a window, and state is a Boolean value defining how the 
flag is to be set. If state is TRUE, the flag is set; if FALSE, the flag is cleared. The 
flag is initially clear, making scrolling illegal. 

The dear ok function sets and clears the clear flag for a given screen. The 
function call has the form: 

clearok( win, state ) 

where win is a pointer to the desired screen, and state is a Boolean value. The 
function sets the flag if state is TRUE, and clears the flag if FALSE. For example, 
the function call 

clearok(stdscr, TRUE) 

sets the clear flag for the standard screen. 

When the clear flag is set, each refresh call to the given screen automatically 
clears the screen by passing a clear-screen sequence to the terminal. This 
sequence affects the terminal only; it does not change the contents of the screen. 

If clear ok is used to set the clear flag for the current screen "curscr", each call to 
refresh automatically clears the screen, regardless of which window is given in 
the call. 



3.5.6 Scrolling a Window 

The scroll function scrolls the contents of a given window upward by one line. 
The function call has the form: 

scroll( win ) 

where win is a pointer to the window to be scrolled. The function should be used 
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The echo function sets the ECHO mode for the terminal, causing each character 
typed at the keyboard to be displayed at the terminal screen. The function call 
has the form: 

echo() 

No arguments are required. 

The n/ function sets a terminal to NEWLINE mode, causing all newline 
characters to be mapped to a corresponding newline and return character 
combination. The function call has the form: 

nl() 

No arguments are required. 

The raw function sets the RAW mode for the terminal, causing each character 
typed at the keyboard to be sent as direct input. The RAW mode disables the 
function of the editing and signal keys and disables the mapping of newline 
characters into newline and return combinations. The function call has the 
form: 

raw() 

No arguments are required. 

3.7.2 Clearing a Terminal Mode 

The noermode, noeeho, nonl, and norava functions clear the current terminal 
mode, allowing input to be processed according to a previous mode. 

The noermode function clears a terminal from the CBREAK mode. The 
function call has the form: 

nocrmodeQ 

No arguments are required. 

The noeeho function clears a terminal from the ECHO mode. This mode 
prevents characters typed at the keyboard from being displayed on the 
terminal screen. The function call has the form: 

noecho() 

No arguments are required. 

The nonl function clears a terminal from NEWLINE mode, causing newline 
characters to be mapped into themselves. This allows the screen processing 
functions to perform better optimization. The function call has the form: 
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The function is normally called by the initeer function. 

3.7.5 Saving and Restoring the Terminal Flags 

The tavetty function saves the current terminal flags, and the reeetty function 
restores the flags previously saved by the tavetty function. These functions are 
performed automatically by initeer and endwin functions. They are not 
required when performing ordinary screen processing. 



3.7.6 Setting a Terminal Type 

The etterm function sets the terminal type to the given type. The function call 
has the form: 

setterm( name ) 

where name is a pointer to a string containing the terminal type identifier. The 
function is normally called by the initeer function, but may be used in special 
cases. 



3.7.7 Reading the Terminal Name 

The longname function converts a given fermcapidentifier into the full name of 
the corresponding terminal. The function call has the form: 

longname( termbuf, name ) 

where termbuf is a pointer to the string containing the terminal type identifier, 
and name is a character pointer to the location to receive the long name. The 
terminal type identifier must exist in the /ete/termeap file. 

The function is typically used to get the full name of the terminal currently 
being used. Note that the current terminal's identifier is stored in the variable 
"ttytype", which may be used to receive a new name. 



3-33 



Chapter 4 

Character and String Processing 



4.1 Introduction 4-1 

4.2 Using the Character Functions 4-1 

4.2.1 Testing for an ASCII Character 4-1 

4.2.2 Converting to ASCII Characters 4-2 

4.2.3 Testing for Alphanumerics 4-2 

4.2.4 Testing for a Letter 4-3 

4.2.5 Testing for Control Characters 4-3 

4.2.6 Testing for a Decimal Digit 4-3 

4.2.7 Testing for a Hexadecimal Digit 4-4 

4.2.8 Testing for Printable Characters 4-4 

4.2.9 Testing for Punctuation 4-4 

4.2.10 Testing for Whitespace 4-5 

4.2.11 Testing for Case in Letters 4-5 

4.2.12 Converting the Case of aLetter 4-5 

4.3 Using the String Functions 4-6 

4.3.1 Concatenating Strings 4-6 

4.3.2 Comparing Strings 4-7 

4.3.3 Copying a String 4-8 

4.3.4 Getting a String's Length 4-8 

4.3.5 Concatenating Characters to a String 4-8 

4.3.6 Comparing Characters in Strings 4-9 

4.3.7 Copying Characters to a String 4-10 

4.3.8 Reading Values from a String 4-10 

4.3.9 Writing Values to a String 4-11 



Character and String Processing 



4.1 Introduction 



Character and string processing is an important part of many programs. 
Programs regularly assign, manipulate, and compare characters and strings in 
order to complete their tasks. For this reason, the standard library provides a 
variety of character and string processing functions. These functions give a 
convenient way to test, translate, assign, and compare characters and strings. 

To use the character functions in a program the file, ctype.k, which provides 
the definitions for special character macros, must be included in the program. 
The line 

^include <ctype.h> 

must appear at the beginning of the program. 

To use the string functions, no special action is required. These functions are 
defined in the standard C library and are read whenever you compile a C 
program. 

4.2 Using the Character Functions 

The character functions test and convert characters. Many character 
functions are defined as macros, and as such cannot be redefined or used as a 
target for a breakpoint when debugging. 

4.2.1 Testing for an ASCII Character 

The isaeeii function tests for characters in the ASCII character set, i.e., 
characters whose values range from to 127. The function call has the form: 

isascii (c) 

where e is the character to be tested. The function returns a nonzero (true) 
value if the character is ASCII, otherwise it returns zero (false). For example, in 
the following program fragment ieaecii determines whether or not the value in 
"c" read from the file given by "data" is in the acceptable ASCII range. 

FILE *data; 
int c; 

c = fgetc(data); 
if (!isascii(c)) 

notext(); 

In this example, a function named notext is called if the character is not in 
range. 
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4.2.4 Testing for a Letter 



The is alpha function tests for uppercase or lowercase letters, i.e., alphabetic 
characters. The function call has the form: 

isalpha (c) 

where e is the character to be tested. The function returns a nonzero (true) 
value if the character is a letter, otherwise it returns zero. For example, the 
function call 

isalpha('a') 
returns a nonzero value, but the call 

isalpha(T) 
returns zero. 

4.2.5 Testing for Control Characters 

The ieentrl function test for control characters, i.e., characters whose ASCII 
values are in the range to 31 or is 127. The function call has the form: 

iscntrl (c) 

where e is the character to be tested. The function returns a nonzero (true) 
value if the character is a control character, otherwise it returns zero (false). 
For example, in the program following fragment ieentrl determines whether or 
not the character in "c" read from the file given by "infile" is a control 
character. 

FILE *infile, *outfile; 
int c; 

c = fgetc(infile); 
if ( Uscntrl(c) ) 

fputc( c, outfile ); 

The fputc function is ignored if the character is a control character. 



4.2.6 Testing for a Decimal Digit 

The iedigit function tests for decimal digits. The function call has the form: 
isdigit (e) 
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neither control characters nor alphanumeric characters. The function call has 
the form: 

ispunct (c) 

where e is the character to be tested. The function returns a nonzero function if 
the character is a punctuation character, otherwise it returns zero. 



4.2.10 Testing for Whitespace 

The isepaee function tests for whitespace characters, i.e, the space, horizontal 
tab, vertical tab, carriage return, formfeed, and newline characters. The 
function call has the form: 

isspace (e) 

where e is the character to be tested. The function returns a nonzero value if 
the character is a whitespace character, otherwise it returns zero. 



4.2.11 Testing for Case in Letters 

The itupper and ielower functions test for uppercase and lowercase letters, 
respectively. The function calk have the form: 

isupper (e) 

and 

islower (c) 

where c is the character to be tested. The function returns a nonzero value if 
the character is the proper case, otherwise it returns zero. For example, the 
function call 

isupper('b') 
returns zero (false), but the call 

islower ('b') 
returns a nonzero (true) value. 

4.2.12 Converting the Case of a Letter 

The tolowtr and toupper functions convert the case of a given letter. The 
function calls have the form: 



4-5 



Character and String Processing 



strcat (det, ere) 



where det is a pointer to the string to receive the new characters, and tre is a 
pointer to the string containing the new characters. The function appends the 
new characters in the same order as they appear in ere, then appends a null 
character (\0) to the last character in the new string. The function always 
returns the pointer det. 

The function is typically used to build a string such as a full pathname from two 
smaller strings. For example, in the following program fragment atrcat 
concatenates the string "temp" to the contents of the character array "dir". 

char dirfMAX] — " /usr/" ; 

strcat(dir, "temp"); 

4.3.2 Comparing Strings 

The et re mp function compares the characters in one string to those in another 
and returns an integer value showing the result of the comparison. The 
function call has the form: 

strcmp (el, e2) 

where el and eS are the pointers to the strings to be compared. The function 
returns zero if the strings are equal (i.e., have the same characters in the same 
order). If the strings are not equal, the function returns the difference between 
the ASCII values of the first unequal pair of characters. The value of the second 
string character is always subtracted from the first. For example, the function 
call 

strcmp(" Character A", "Character A"); 
returns zero since the strings are identical in every way, but the function call 

strcmpf Character A", "Character B"); 

returns-1 since the ASCII value of "B" isone greater than "A". 

Note that the etremp function continues to compare characters until a 
mismatch is found. If one string is shorter than the other, the function usually 
stops at the end of the shorter string. For example, the function call 

strcmp(" Character A", "Character ") 

returns 65, that is, the difference between the null character at the end of the 
second string and the "A" in the first string. 
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strncat (det, ere, n) 



where dst is a pointer to the string to receive the new characters, arc is a pointer 
to the string containing the new characters, and n is an integer value giving the 
number of characters to be concatenated. The function appends the given 
number of characters to the end of the dtt string, then returns the pointer d$t. 

In the following program fragment, ttrncat copies the first three characters in 
"letter" to the end of "cover". 

char cover [1 = "cover"; 
char letter[J — "letter"; 

strncat( cover, letter, 3); 

This example creates the new string "coverlet" in "cover". 

4.3.6 Comparing Characters in Strings 

The etrncmp function compares one or more pairs of characters in two given 
strings and returns an integer value which gives the result of the comparison. 
The function call has the form: 

strncmp ($1, eS, n) 

where el and $2 are pointers to the strings to be compared, and n is an integer 
value giving the number of characters to compare. The function returns zero if 
the first n characters are identical. Otherwise, the function returns the 
difference between the ASCII values of the first unequal pair of characters. The 
function generates the difference by subtracting the second string character 
from the first. 

For example, the function call 

strncmp(" Character A" , " Character B" , 5) 
returns zero because the first five characters are identical, but the function call 

strncmpf Character A", "Character B", 11) 

returns-1 because the value of "B" is one greater than "A". 

Note that the function continues to compare characters until a mismatch or the 
end of a string is found. 
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char datestrfl — {"THU MAR 28 11:04:40 EST 1983"}; 
char month[4]; 
char year [5]; 

sscanf(datestr," %*3s%3s%*2s%*8s%*3s%4s" ,month,year); 
printf("%s, %s\n" ,month,year); 

The first value (a three-character string) is stored at the location pointed to by 
"month", the second value (a four-character string) is stored at the location 
pointed to by "year". 



4.3.0 Writing Values to a String 

The sprint/ function writes one or more values to a given string. The function 
call has the form: 

sprintf (», format [, arg] . . . ) 

where $ is a pointer to the string to receive the value, format is a pointer to a 
string which defines the format of the values to be written, and arg is the 
variable or value to be written. If more than one arg is given, they must be 
separated by commas (,). The format string may contain the same formats as 
given for print/ (see pri ntf(S) in the XENIX Reference Manual). After all values 
are written to the string, the function adds a null character (\0) to the end of 
the string. The function normally returns zero, but will return a nonzero value 
if an error is encountered. 

The function is typically used to build a large string from several values of 
different format. For example, in the following program fragment tprintf 
writes three values to the string pointed to by "cmd". 

char cmd[100]; 

char *doc = "/usr/src/cmd/cp.c" 

int width = 50; 

int length = 60; 

sprintf(cmd,"pr -w%d -l%d %s\n",width,length,doc); 
system(cmd); 

In this example, the string created by $printf is used in a call to the tyetem 
function. The first two values are the decimal numbers given by "width" and 
"length". The last value is a string (a filename) and is pointed to by doe. The 
final string has the form: 

pr -w50 -160 /usr/src/cmd/cp.c 

Note that the string to receive the values must have sufficient length to store 
those values. The function cannot check for overflow. 
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Using Process Control 



5.1 Introduction 



This chapter describes the process control functions of the standard C library. 
The functions let a program call other programs, using a method similar to 
calling functions. 

There are a variety of process control functions. The ey$tema.nd exit functions 
provide the highest level of execution control and are used by most programs 
that need a straightforward way to call another program or terminate the 
current one. The excel, execv, fork, and wait functions provide low-level 
control of execution and are for those programs which must have very fine 
control over their own execution and the execution of other programs. Other 
process control functions such as abort and exec are described in detail in 
section SoftheXENIX Reference Manual. 

The process control functions are a part of the standard G library. Since this 
library is automatically read when compiling a C program, no special library 
argument is required when invoking the compiler. 



5.2 Using Processes 

"Process" is the term used to describe a program executed by the XENIX 
system. A process consists of instructions and data, and a table of information 
about the program, such as its allocated memory, open files, and current 

execution status. 

You create a process whenever you invoke a program through a shell. The 
system assigns a unique process ID to a program when it is invoked, and uses 
this ID to control and manage the program. The unique IDs are needed in a 
system running several processes at the same time. 

You can also create a process by directing a program to call another program. 
This causes the system to perform the same functions as when it invokes a 
program through a shell. In fact, these two methods are actually the same 
method; invoking a program through a shell is nothing more than directing a 
program (the shell) to call another program. 

The system handles all processes in essentially the same way, so the sections 
that follow should give you valuable information for writing your own 
programs and an insight into the XENIX system itself. 



5.3 Calling a Program 

The tyetem function calls the given program, executes it, and then returns 
control to the original program. The function call has the form: 
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exit (status) 

where status is the integer value to be sent to the system as the termination 
status. 

The function is typically used to terminate a program before its normal end, 
such as after a serious error. For example, in the following program fragment 
exit stops the program and sends the integer value "2" to the system if the 
/openfunction returns the null pointer valueNULL. 

FILE *ttyout; 

if ( fopen(ttyout,"r") =.= NULL ) 
exit(2); 

Note that the exit function automatically closes each open file in the program 
before returning to the system. This means no explicit calls to the /close or 
close functions are required before an exit. 



5.5 Starting a New Program 

The execl and execv functions cause the system to overlay the calling program 
with the given one, allowing the calling program to terminate while the new 
program continues execution. 

The execl function call has the form: 

execl (pathname, command- name, argptr ...) 

where pathname is a pointer to a string containing the full pathname of the 
command you want to execute, command-name is a pointer to a string 
containing the name of the program you want to execute, and argptr is one or 
more pointers to strings which contain the program arguments. Each argptr 
must be separated from any other argument by a comma. The last argptrin the 
list must be the null pointer value NULL. For example, in the call 

execlf /bin/date", "date", NULL); 

the date command, whose full pathname is "/bin/date", takes no arguments, 
and in the call 

execlf /bin/cat", "cat", filel, file2, NULL); 

the cat command, whose full pathname is "/bin/cat", takes the pointers 
"filel" and "file2" as arguments. 

The execv function call has the form: 
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If the program display is not found or lacks the necessary permissions, the 
original program resumes control and displays an error message. 

Note that the excel and exeev functions will not expand metacharacters (e.g., 
<, >, *, ?, and []) given in the argument list. If a program needs these features, 
it can use execlor exeev to call a shell as described in the next section. 



5.6 Executing a Program Through a Shell 

One drawback of the exeel and exeev functions is that they do not provide the 
metacharacter features of a shell. One way to overcome this problem is to use 
exeelto execute a shell and let the shell execute the command you want. 

The function call has the form: 

execl ("/bin/shVshV-c", command-line, NULL); 

where command-line is a pointer to the string containing the command line 
needed to execute the program. The string must be exactly as it would appear if 
typed at the terminal. 

For example, a program can execute the command 

cat *.c 
(which contains the metacharacter * ) with the call 

execl(7bin/sh", "ah", "-c", "cat *.c", NULL); 

In this example, the full pathname fbin/sh and command name th start the 
shell. The argument "-c" causes the shell to treat the argument "cat *.c" as a 
whole command line. The shell expands the metacharacter and displays all files 
which end with .c, something that the cat command cannot do by itself. 

5.7 Duplicating a Process 

The fork function splits an executing program into two independent and fully- 
functioning processes. The function call has the form: 

fork () 

No arguments are required. 

The function is typically used to make multiple copies of any program that 
must take divergent actions as a part of its normal operation, e.g., a program 
that must use the execl function yet still continue to execute. The original 
program, called the "parent" process, continues to execute normally, just as it 
would after any other function call. The new process, called the "child" 
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int status; 

char * path name; 

char *cmd[ ]; 

if (fork() == 0) 

execv(pathname, cmd); 
wait(&status); 

The wait function always copies a status value to its argument. The status 
value is actually two 8-bit values combined into one. The low-order 8 bits is the 
termination status of the child as defined by the system. This status is zero for 
normal termination and nonzero for other kinds of termination, such as 
termination by an interrupt, quit, or hangup signal (see $ignal[S) in the XENIX 
Refe renee Manual for a description of the various kinds of termination). The 
next 8 bits is the termination status of the child as defined by itsown call to exit. 
If the child did not explicitly call the function, the status is zero. 



5.9 Inheriting Open Files 

Any program called by another program or created as a child process to 
aprogram automatically inherits the original program's open files and 
standard input, output, and error files. This means if the file was open in the 
original program, it will be open in the new program or process. 

A new program also inherits the contents of the input and output buffers used 
by the open files of the original program. To prevent a new program or process 
from reading or writing data that is not intended for its use, these buffers 
should be flushed before calling the program or creating the new process. A 
program can flush an output buffer with the jflueh function, and an input buffer 
■wiihtetbuf. 



5.10 Program Example 

This section shows how to use the process control functions to control a simple 
process. The following program starts a shell on the terminal given in the 
command line. The terminal is assumed to be connected to the system through 
a line that has not been enabled for multiuser operation. 
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6.1 Introduction 



A pipe is an artifical file that a program may create and use to pass information 
to other programs. A pipe is similar to a file in that it has a file pointer and/or a 
file descriptor and can be read from or written to using the input and output 
functions of the standard library. Unlike a file, a pipe does not represent a 
specific file or device. Instead a pipe represents temporary storage in memory 
that is independent of the program's own memory and is controlled entirely by 
the system. 

Pipes are chiefly used to pass information between programs, just as the shell 
pipe symbol ( | ), is used to pass the output of one program to the input of 
another. This eliminates the need to create temporary files to pass information 
to other programs. A pipe can also be used as a temporary storage place for a 
single program. A program can write to the pipe, then read that information 
back at a later time. 

The standard library provides several pipe functions. The popen and peloee 
functions control both a pipe and a process. The popen function opens a pipe 
and creates a new process at the same time, making the new pipe the standard 
input or output of the new process. The pclose function closes the pipe and 
waits for termination of the corresponding process. The pipe function, on the 
other hand, gives low-level access to a pipe. The function is similar to the open 
function, but opens the pipe for both reading and writing, returning two file 
descriptors instead of one. The program can either use both sides of the pipe or 
close the one it does not need. The low-level input and output functions read 
and write can be used to read from and write to a pipe. Pipe file descriptors are 
used in the same way as other file descriptors. 



6.2 Opening a Pipe to a New Process 

The popen function creates a new process and then opens a pipe to the standard 
input or output file of that new process. The function call has the form: 

popen [command, type) 

where command is a pointer to a string that contains a shell command line, and 
type is a pointer to the string which defines whether the pipe is to be opened for 
reading or writing by the original process. It may be "r" for reading or "w" for 
writing. The function normally returns the file pointer to the open pipe, but 
will return the null pointer value NULL if an error is encountered. 

The function is typically used in programs that need to call another program 
and pass substantial amounts of data to that program. For example, in the 
following program fragment popen creates a new process for the cat command 
and opens a pipe for writing. 
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where stream is the file pointer of the pipe to be closed. The function normally 
returns the exit status of the command that was issued as the first argument of 
its corresponding pppen, but will return the value-l if the pipe was not opened 
by pope n. 

For example, in the following program fragment pcloee closes the pipe given by 
"pstrm" if the end-of-file value EOF has been found in the pipe. 

FILE *pstrm; 

if (feof(pstrm)) 

pclose (pstrm); 



6.5 Opening a Low-Level Pipe 

The pipe function opens a pipe for both reading and writing. The function call 
has the form: 

pipe (fd) 

where fd is a pointer to a two-element array. It must have int type. Each 
element receives one file descriptor. The first element receives the file 
descriptor for the reading side of the pipe, and the other element receives the 
file descriptor for the writing side. The function normally returns 0, but will 
return the value -1 if an error is encountered. For example, in the following 
program fragment pipe creates two file descriptors if no error is encountered. 

int chan[2]; 

if (pipe(chan) ===== -1) 
exit(2); 

The array element "chan(0j" receives the file descriptor for the reading side of 
the pipe, and "chanjlj" receives it for the writing side. 

The function is typically used to open a pipe in preparation for linking it to a 
child process. For example, in the following program fragment pipe causes the 
program to create a child process if it successfully creates a pipe. 

int fd[2]; 

if (pipe(fd) != -1) 

if ( fork() == ) 
close(fd[l]); 

Note that the child process closes the writing side of the pipe. The parent can 
now pass data to the child by writing to the pipe; the child can retrieve the data 
by reading the pipe. 
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The system copies the end-of-file value EOF to a pipe when the process that 
made the original pipe and every process created or called by that process has 
closed the writing side of the pipe. This means, for example, that if a parent 
process is sending data to a child process through a pipe and closes the pipe to 
signal the end of the file, the child process will not receive the end-of-file value 
unless it has already closed its own write side of the pipe. 

8.8 Program Examples 

This section shows how to use the process control functions with the low-level 
pipe function to create functions similar to the popcn and pcloee functions. 

The first example is a modified version of the popen function. The modified 
function identifies the new pipe with a file descriptor rather than a file pointer. 
It also requires a "mode" argument rather than a "type" argument, where the 
mode is for reading or 1 for writing. 

#include <stdio.h> 

#define READ 

#define WRITE 1 

#define tst(a, b) (mode == READ ? (b) : (a)) 

static int popen_pid; 

popen(cmd, mode) 
char *cmd; 
int mode; 

{ 

int p[2j; 

if (pipe(p) < 0) 

return(NULL); 

if ((popen_pid = forkQ) == 0) { 

close(tst(p[WRITE], p[READ])); 
close(tst(0, 1)); 

dup(tst(p[READ], p[WRITE])); 
close(tst(p[READj, p[WRITE])); 
execlf/bin/sh", "sh", "-c", cmd, 0); 
exit(l); /* sh cannot be found */ 

if (popen_pid == -1) 
return(NULL); 

close(tst(p[READ], p[WRITE])); 
return(tst(p[WRITE], p[READ])); 

The function creates a pipe with the pipe function first. It then uses the fork 
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^include <signal.h> 



pclose(fd) /* close pipe fd »/ 

int fd; 

{ 

int r, status; 

int (*hstat)(), (*istat)(), (*qstat)(); 
extern int popen_pid; 

close(fd); 

istat — signal(SIGINT, SIG IGN); 
qstat = signal(SIGQUIT, SIGJGN); 
hstat = signal(SIGHUP, SIGJGN); 

while ((r ■» wait(festatus)) !—». popen_pid && r !■» -1) 

if(r—'-l) 

status = -1; 

signal(SIGINT, istat); 
signal(SIGQUIT, qstat); 
signal(SIGHUP, hstat); 

return(status); 



} 



The function closes the pipe first. It then uses a while statement to wait for the 
child process given by "popen_pid". If other child processes terminate while it 
waits, it ignores them and continues to wait for the given process. It stops 
waiting as soon as the given process terminates or if no child process exists. The 
function returns the termination status of the child, or the value -1 if there was 
an error. 

The eignal function calls used in this example ensure that no interrupts 
interfere with the waiting process. The first set of functions causes the process 
to ignore the interrupt, quit, and hang up signals. The last set restores the 
signals to their original status. The eignal function is described in detail in 
Chapter 7, "Using Signals". 

Note that both example functions use the external variable "popenj>id" to 
store the process ID of the child process. If more than one pipe is to be opened, 
the "popen_pid" value must be saved in another variable before each call to 
popen, and this value must be restored before calling pelote to close the pipe. 
The functions can be modified to support more than one pipe by changing the 
"popen_pid" variable to an array indexed by file descriptor. 
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7.1 Introduction 



This chapter explains how to use C library functions to process signals sent to a 
program by the XENIX system. A signal is the system's response to an unusual 
condition that occurs during execution of a program such as a user pressing the 
INTERRUPT key or the system detecting an illegal operation. A signal 
interrupts normal execution of the program and initiates an action such as 
terminating the program or displaying an error message. 

The atyn a/ function of the standard C library lets a program define the action of 
a signal. The function can be used to disable a signal to prevent it from affecting 
the program. It can also be used to give a signal a user-defined action. 

The eignal function is often used with the eetjmp and longjmp functions to 
redefine and reshape the action of a signal. These functions allow programs to 
save and restore the execution state of a program, giving a program a means to 
jump from one state of execution to another without a complex assembly 
language interface. 

To use the eignal function, you must add the line 

#include <signal.h> 

to the beginning of the program. The eignal. h file defines the various manifest 
constants used as arguments by the function. To use the eetjmp and longjmp 
functions you must add the line 

#include <setjmp.h> 

to the beginning of the program. The eetjmp. h file contains the declaration for 
the type j mp_buf, a template for saving a program's current execution state. 



7.2 Using the signal Function 

The eignal function changes the action of a signal from its current action to a 
given action. The function has the form 

signal (eigtype, ptr) 

where eigtype is an integer or a mainfest constant that defines the signal to be 
changed, and ptr is a pointer to the function defining the new action or a 
manifest constant giving a predefined action. The function always returns a 
pointer value. This pointer defines the signal's previous action and may be used 
in subsequent calls to restore the signal to its previous value. 

The ptr may be "SIG_IGN" to indicate no action (ignore the signal) or 
"SIG_DFL" to indicate the default action. The eigtype may be "SIGINT" for 
interrupt signal, caused by pressing the INTERRUPT key, "SIGQUIT" for quit 
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^include <signal.h> 

main () 
{ 

if ( fork() «« 0) { 

signal(SIGINT, SIGJGN); 
/* Child process. */ 

} 

/* Parent process. */ 

} 

This call does not affect the parent process which continues to receive 
interrupts as before. Note that if the parent process is interrupted, the child 
process continues to execute until it reaches its normal end. 

7.2.2 Restoring a Signal's Default Action 

You can restore a signal to its default action by using the "SIGJDFL" constant 
with signal. The function call has the form 

signal [eigtypt, SIGDFL) 

where tigtype is the manifest constant defining the signal you wish to restore. 
For example, the function call 

signal (SIGINT, SIG.DFL) 

restores the interrupt signal to its default action. 

The function call is typically used to restore a signal after it has been 
temporarily disabled to keep it from interrupting critical operations. For 
example, in the following program fragment the second c&Uko sign d restores 
the signal to its default action. 
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#include <signal.h> 



main () 
{ 



} 

catch () 
{ 



} 



int catch (); 

printf(" Press INTERRUPT key to stop.O); 
signal (SIGINT, catch); 
while () { 

/* Body */ 
} 



printf(" Program terminated.\n" ); 
exit(l); 



The cafe A function prints the message "Program terminated" before stopping 
the program with the exit function. 

A program may redefine the action of a signal at any time. Thus, many 
programs define different actions for different conditions. For example, in the 
following program fragment the action of the interrupt signal depends on the 
return value of a function named keyteet. 

#include <signal.h> 



main () 
{ 



int catch 1 (), catch2 (); 

if (keytest() — ■- 1) 

signal(SIGINT, catchl); 
else 

signal(SIGINT, catch2); 



Later the program may change the signal to the other action or even a third 
action. 

When using a function pointer in the eignal call, you must make sure that the 
function name is defined before the call. In the program fragment shown above, 
cafe Aland catehS are explicitly declared at the beginning of the main program 
function. Their formal definitions are assumed to appear after the eignal call. 
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# include <stdio.h> 
#include <signal.h> 

system(s) /* run command string s */ 

char *s; 

{ 

int status, pid, w; 

register int (*istat)(), (*qstat)(); 

if ((pid - forkO) == 0) { 

execl(7bin/sh B , "sh", B -c", s, NULL); 
exit(127); 

} 

istat = signal(SIGINT, SIGJGN); 

qstat — signal(SIGQUIT, SIGJGN); 

while ((w = wait(&status)) != pid && w !=» -1) 

if ( w == -1) 

status = -1; 
signal(SIGINT, istat); 
signal(SIGQUIT, qstat); 
return(status); 

} 

Note that the parent uses the while statement to wait until the child's process 
ID "pid" is returned by wait . If wait returns the error code "-1" no more child 
processes are left, so the parent returns the error code as its own status. 



7.3 Controlling Execution With Signals 

Signals do not need to be used solely as a means of immediately terminating a 
program. Many signals can be redefined to delay their actions or even cause 
actions that terminate a portion of a program without terminating the entire 
program. The following sections describe ways that signals can be caught and 
used to provide control of a program. 



7.3.1 Delaying a Signal's Action 

You can delay the action of a signal by catching the signal and redefining its 
action to be nothing more than setting a globally-defined flag. Such a signal 
does nothing to the current execution of the program. Instead, the program 
continues uninterrupted until it can test the flag to see if a signal has been 
received. It can then respond according to the value of the flag. 

The key to a delayed signal is that all functions return execution the exact point 
at which the program was interrupted. If the function returns normally the 
program continues execution just as if no signal occurred. 
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receives a signal when reading the terminal, all characters read before the 
interruption are lost, making it appear as though no characters were typed. 

Whenever a program intends to use delayed signals during calls to system 
functions, the program should include a check of the function return values to 
ensure that an error was not caused by an interruption. In the following 
program fragment, the program checks the current value of the interrupt flag 
"intflag" to make sure that the value EOF returned by getehar actually 
indicates the end of the file. 

if (getchar() == EOF) 
if (intflag) 

/* EOF caused by interrupt */ 
else 

/* true end-of-file */ 



7.3.3 Using Signals in Interactive Programs 

Signals can be used in interactive programs to control the execution of the 
program's various commands and operations. For example, a signal may be 
used in a text editor to interrupt the current operation (e.g., displaying a file) 
and return the program to a previous operation (e.g., waiting for a command). 

To provide this control, the function that redefines the signal's action must be 
able to return execution of the program to a meaningful location, not just the 
point of interruption. The standard C library provides two functions to do 
this: $etjmp and longjmp. The eetjmp function saves a copy of a program's 
execution state. The longjmp function changes the current execution state to a 
previously saved state. The functions cause a program to continue execution at 
an old location with old register values and status as if no operations had been 
performed between the time the state was saved and the time it was restored. 

The Bttjmp function has the form 

setjmp (buffer) 

where buffer is the variable to receive the execution state. It must be explicitly 
declared with type jmpbuf before it is used in the call. For example, in the 
following program fragment eetbuf copies the execution of the program to the 
variable "oldstate" defined with type jmpbuf. 

jmpbuf oldstate; 

setbuf(oldstate); 

Note that after a »ct6tt/call, the buffer variable contains values for the program 
counter, the data and address registers, and the process status. These values 
must not be modified in any way. 
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7.4.1 Protecting Background Processes 



Any program that has been invoked using the shell's background symbol (&) is 
executed as a background process. Such programs usually do not use the 
terminal for input or output, and complete their tasks silently. Since these 
programs do not need additional input, the shell automatically disables the 
signals before executing the program. This means signals generated at the 
terminal do not affect execution of the program. This is how the shell protects 
the program from signals intended for other programs invoked from the same 
terminal. 

In some cases, a program that has been invoked as a background process may 
also attempt to catch its own signals. If it succeeds, the protection from 
interruption given to it by the shell is defeated, and signals intended for other 
programs will interrupt the program. To prevent this, any program which is 
intended to be executed as a background process, should test the current state 
of a signal before redefining its action. A program should redefine a signal only 
if the signal has not been disabled. For example, in the following program 
fragment the action of the interrupt signal is changed only if the signal is not 
currently being ignored. 

#include <signal.h> 



main() 
{ 



int catch(); 

if (signal(SIGINT, SIGJGN) !- SIGJGN) 
signal(SIGINT, catch); 

/* Program body. */ 



This step lets a program continue to ignore signals if it is already doing so, and 
change the signal if it is not. 
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8.1 Introduction 



This chapter describes the standard C library functions that let programs 
share the resources of the XENIX system. The functions give a program the 
means to queue for the use and control of a given resource and to synchronize its 
use with use by other programs. 

In particular, this chapter explains how to 

— Allocate memory for dynamically required storage 

— Lock a file to ensure exclusive use by a program 

— Use semaphores to control access to a resource 

— Share data space to allow interaction between programs 



8.2 Allocating Space 

Some programs require significant changes to the size of their allocated 
memory space during different phases of their execution. The memory 
allocation functions of the standard C library let programs allocate space 
dynamically. This means a program can request a given number of bytes of 
storage for its exclusive use at the moment it needs the space, then free this 
space after it has finished using it. 

There are four memory allocation functions: malloe, calloc, ralloc, and/ree. 
The malloe and calloc functions are used to allocate space for the first time. 
The functions allocate a given number of bytes and return a pointer to the new 
space. The re alloc function reallocates an existing space, allowing it to be used 
in a different way. The free function returns allocated space to the system. 



8.2.1 Allocating Space for a Variable 

The malloe function allocates space for a variable containing a given number of 
bytes. The function call has the form: 

malloe (size) 

where eize is an unsigned number which gives the number of bytes to be 
allocated. For example, the function call 

table = malloe (4) 

allocates four bytes or storage. The function normally returns a pointer to the 
starting address of the allocated space, but will return the null pointer value if 
there is not enough space to allocate. 
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8.2.3 Reallocating Space 



The realloe function reallocates the space at a given address without changing 
the contents of the memory space. The function call has the form: 

realloe (ptr, eize) 

where ptr is a pointer to the starting address of the space to be reallocated, and 
eize is an unsigned number giving the new size in bytes of the reallocated space. 
The function normally returns a pointer to the starting address of the allocated 
space, but will return a null pointer value if there is not enough space to 
allocate. 

This function is typically used to keep storage as compact as possible. For 
example, in the following program fragment realloe is used to remove table 
entries. 

main () 

{ 

char * table; 
int i; 
unsigned inum; 

for (i=inum; i>-l; i—) { 

printf(" %d0, strings[i|); 
strings = realloc(strings, i*4); 

} 

In this example, an entry is removed after it has been printed at the standard 
output, by reducing the size of the allocated space from its current length to the 
length given by "i*4". 



8.2.4 Freeing Unused Space 

The free function frees unused memory space that had been previously 
allocated by a malloc, e alloc, or realloe function call. The function call has the 
form: 

free {ptr) 

where ptr is the pointer to the starting address of the space to be freed. This 
pointer must be the return value of a malloc, calloc, or re alloc function. 

The function is used exclusively to free space which is no longer used or to free 
space to be used for other purposes. For example, in the following program 
fragment free frees the allocated space pointed to by "strings" if the first 
element is equal to zero. 
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8.3.2 Locking a File 



The locking function locks one or more bytes of a given file. The function call 
has the form: 

locking (file dee, mode, tize) 

where filedee is the file descriptor of the file to be locked, mode is an integer 
value which defines the type of lock to be applied to the file , tize is a long integer 
value giving the size in bytes of the portion of the file section to be locked or 
unlocked. The mode may be "LOCK" for locking the given bytes, or 
"UNLOCK" for unlocking them. For example, in the following program 
fragment locking locks 100 bytes at the current character pointer position in 
the file given by "fd". 

# include <sys/locking.h> 

main () 

\ 

int fd, 

fd = open("data", 2); 
locking(fd, LOCK, 100); 

The function normally returns the number of bytes locked, but will return -1 if 
it encounters an error. 



8.3.3 Program Example 

This section shows how to lock and unlock a small section in a file using the 
locking function. In the following program, the function locks 100 bytes in the 
file data which is opened for reading and writing. The locked portion of the file 
is accessed, then lockingis used again to unlock the file. 
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8.4.1 Creating a Semaphore 



The ereateem function creates a semaphore, returning a semaphore number 
which may be used in subsequent semaphore functions. The function call has 
the form: 

creatsem (sem_name, mode) 

where eem_name is a character pointer to the name of the semaphore, and 
mode is an integer value which defines the access mode of the semaphore. 
Semaphore names have the same syntax as regular file names. The names must 
be unique. The function normally returns an integer semaphore number which 
may be used in subsequent semaphore functions to refer to the semaphore. The 
function returns -1 if it encounters an error, such as creating a semaphore that 
already exists, or using the name of an existing regular file. 

The function is typically used at the beginning of one process to clearly define 
the semaphores it intends to share with other processes. For example, in the 
following program fragment creatsem creates a semaphore named "ttyl" 
before preceding with its tasks. 

main () 

{ 

int ttyl; 

FILE fttyl; 

ttyl = creatsem("ttyr, 0777); 
fttyl — fopenC/dev/ttyOl", "w"); 
/* Program body. */ 

} 

Note that /open is used immediately after creatsem to open the file /devfttyOl 
for writing. This is one way to make the association between a semaphore and a 
device clear. 

The mode "0777" defines the semaphore's access permissions. The permissions 
are similar to the permissions of a regular file. A semaphore may have read 
permission for the owner, for users in the same group as the owner, and for all 
other users. The write and execution permissions have no meaning. Thus, 
"0777" means read permission for all users. 

No more than one process ever need create a given semaphore; all other 
processes simply open the semaphore with the ope nsem function. Once created 
or opened, a semaphore may be accessed only by using the waitsem, 
nbwaiteem, or eigeem functions. The creatsem function may be used more 
than once during execution of a process. In particular, it can be used to reset a 
semaphore if a process fails to relinquish control before terminating. 
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semaphore that does not exist or requesting a semaphore that is locked to a 
dead process. 

The function is used whenever a given process wishes to access the device or 
system resource associated with the semaphore. For example, in the following 
program fragment waiteem signals the intention to write to the file given by 
"ttyl". 

main () 

{ 

int ttyl; 
FILE fttyl; 

waitsem( ttyl ); 

fprintf( fttyl, "Changing tty driver\n"); 

The function waits until current controlling process relinquishes control of the 
semaphore before returning to the next statement. 



8.4.4 Checking the Status of a Semaphore 

The nbwaiteem function checks the current status of a semaphore. If the 
semaphore is not available, the function returns an error value. Otherwise, it 
gives immediate control of the semaphore to the calling process. The function 
call has the form: 

nbwaitsem (eemjnum) 

where eem_num is the semaphore number of the semaphore to be checked. The 
function returns -1 if it encounters an error such as requesting a semaphore 
that does not exist. The function also returns -1 if the process controlling the 
requested semaphore terminates without relinquishing control of the 
semaphore. 

The function is typically used in place of waiteem to take control of a 
semaphore. 



8.4.5 Relinquishing Control of a Semaphore 

The tigse m function causes a process to relinquish control of a given semaphore 
and to signal this fact to all processes waiting for the semaphore. The function 
call has the form: 

sigsem («cm_n«m) 

where eem_num is the semaphore number of the semaphore to relinquish. The 
semaphore must have been previously created or opened by the process. 
Furthermore, the process must have been previously taken control of the 
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#define NPROC 5 

char semf[] ■« "JcesemfXXXXXX"; 
int sem_num; 

int holdsem ™ 5; 



main () 
{ 



} 



register i, chid; 

mktemp(semf); 

if ((sem_num ■« creatsem(semf, 0777)) < 0) 

err("creatsem"); 
for (i — 1; i < NPROC; ++i) { 
if ((chid « forkj)) < 0) 

err("No fork"); 
else if(chid == 0) { 

if((sem_num ■■ opensem(semf)) < 0) 

err("opensem"); 
doit(i); 
exit(0); 
} 
} 

doit(0); 
for (i — 1; i < NPROC; ++i) 

while(wait((int *)0) < 0) 

* 
unlink(semf); 



doit(id) 

while(holdsem — ) { 

if(waitsem(sem_num) < 0) 

errCwaitsem"); 
printf( B %d\n", id); 
sleep(l); 

if(sigsem(sem_num) < 0) 
err("sigsem"); 
} 
} 

err(s) 
char *s; 

{ 

perror(s); 

exit(l); 
} 
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8.5.1 Creating a Shared Data Segment 



The edget function creates a shared data segment for the current process, or if 
the segment already exists, attaches the segment to the data space of the 
current process. The function call has the form: 

sdget [path, flag [, $ize, mode ] ) 

where path is a character pointer to a valid pathname, flag is an integer value 
which defines how the segment should be created or attached, eize is an integer 
value which defines the size in bytes of the segment to be created, and mode is 
an integer value which defines the access permissions to be given to the segment 
if created. The rize and mode values are used only when creating a segment. 
The flag may be SD_RDONLY for attaching the segment for reading only, 
SD_WRITE for attaching the segment for reading and writing, SDjCREAT for 
creating the segment given by path if it does not already exist, or SD_UNLOCK 
for allowing simultaneous access by multiple processes. The values can be 
combined by logically ORing them. The SDJJNLOCK value is used only if the 
segment is created. The function returns the address of the segment if it has 
been successfully created or attached. Otherwise, the function returns -1 if it 
encounters an error. 

The function is most often used to create a segment to be shared by another 
process. The function may then be used in the other process to attach the 
segment to its data space. For example, in the following program fragment 
sdget creates a segment and assigns the address of the segment to "shared". 

^include <sd.h> 

main () 

{ 

char *shared, *spath; 

shared — sdget( spath, SD_CREAT, 512, 0777 ); 
} 

When the segment is created, the size "512" and the mode "0777" are used to 
define the segment's size in bytes and access permissions. Access permissions 
are similar to permissions given to regular files. A segment may have read or 
write permission for the owner of the process, for users belonging to the same 
group as the owner, and for all other users. Execute permission for a segment 
has no meaning. For example, the mode "0777" means read and write 
permission for everyone, but "0660" means read and write permissions for the 
owner and group processes only. When first created, a segment is filled with 
zeroes. 

Note that the SD_UNLOCK flag used on systems without hardware support for 
shared data may severely degrade the execution performance of the program. 
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#include <sd.h> 

main () 

{ 

char *shared; 

while ( *x++ !— ) { 

sdenter(shared); 

/* write to segment */ 

sdleave(shared); 

} 

} 



8.5.4 Getting the Current Version Number 

The edgetv function returns the current version number of the given data 
segment. The function call has the form: 

sdgetv (addr) 

where addr is a character pointer to the desired segment. A segment's version 
number is initially zero, but it is incremented by one whenever a process leaves 
the segment using the edit ave function. Thus, the version number is a record of 
the number of times the segment has been accessed. The function's return 
value is always an integer. It returns -1 if it encounters an error. 

The function is typically used to choose an action based on the current version 
number of the segment. For example, in the following program fragment 
sdgetv determines whether or not edenter should be used to enter the segment 
given by "shared". 

#$include <sd.h> 

main () 

{ 

char *shared; 

if (sdgetv(shared) > 10) 
sdenter(shared); 

In this example, the segment is entered if the current version number of the 
segment is greater than "10". 



8.5.5 Waiting for a Version Number 

The edwaitv function causes a process to wait until the version number for the 
given segment is no longer equal to a given version number. The function call 
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Error Processing 



9.1 Introduction 



The XENIX system automatically detects and reports errors that occur when 
using standard C library functions. Errors range from problems with accessing 
files to allocating memory. In most cases, the system simply reports the error 
and lets the program decide how to respond. The XENIX system terminates a 
program only if a serious error has occurred, such as a violation of memory 
space. 

This chapter explains how to process errors, and describes the functions and 
variables a program may use respond to errors. 



9.2 Using the Standard Error File 

The standard error file is a special output file that can be used by a program to 
display error messages. The standard error file is one of three standard files 
(standard input, output, and error) automatically created for the program 
when it is invoked. 

The standard error file, like the standard output, is normally assigned to the 
user's terminal screen. Thus, error messages written to the file are displayed at 
the screen. The file can also be redirected by using the shell's redirection 
symbol (>) For example, the following command redirects the standard error 
file to the file errorliet. 

dial 2>errorlist 

In this case, subsequent error messages are written to the given file. 

The standard error file, like the standard input and standard output, has 
predefined file pointer and file descriptor values. The file pointer stderrmay 
be used in stream functions to copy data to the error file. The file descriptor 2 
may be used in low-level functions to copy data to the file. For example, in the 
following program fragment stderr is used to write the message "Unexpected 
end of file" to the standard error file. 

if((c=geccaar())==EOF) 

fprintf (stderr, "Unexpected end of file.\n"); 

The standard error file is not affected by the shell's pipe symbol (|). This means 
that even if the standard output of a program is piped to another program, 
errors generated by the program will still appear at the terminal screen (or in 
the appropriate file if the standard error is redirected). 



9.3 Using the errno Variable 

The errno variable is a predefined external variable which contains the error 
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accounts: Permission denied. 

if errno is equal to the constant EACCES. 

if ( errno «*— EACCES ) { 
perror(" accounts"); 
fd — open f/usr/tmp/accounts", 0_RDONLY); 

} 

All error messages displayed by perror are stored in an array named 
sys_errno, an external array of character strings. The perror function uses 
the variable errno as the index to the array element containing the desired 
message. 



9.5 Using Error Signals 

Some program errors cause the XENIX system to generate error signals. These 
signals are passed back to the program that caused the error and normally 
terminate the program. The most common error signals are SIGBUS, the bus 
error signal, SIGFPE, the floating point exception signal, SIGSEGV, the segment 
violation signal, SIGSYS, the system call error signal, and SIGPIPE, the pipe 
error signal. Other signals are described in eignal(S) in the XENIX Reference 
Manual. 

A program can, if necessary, catch an error signal and perform its own error 
processing by using the eignal function. This function, as described in Chapter 
7, "Using Signals" can set the action of a signal to a user-defined action. For 
example, the function call 

signal(SIGBUS, fixbus); 

sets the action of the bus error signal to the action defined by the user-supplied 
function fixbu$. Such a function usually attempts to remedy the problem, or at 
least display detailed information about the problem before terminating the 
program. 

For details about how to catch, redefine, and restore these signals, see Chapter 
7. 



9.6 Encountering System Errors 

Programs that encounter serious errors, such as hardware failures or internal 
errors, generally do not receive detailed reports on the cause of the errors. 
Instead, the XENIX system treats these errors as "system errors", and reports 
them by displaying a system error message on the system console. This section 
briefly describes some aspects of XENIX system errors and how they relate to 
user programs. For a complete list and description of XENIX system errors, see 
meeeagee(M) intheXEKTX Reference Manual. 
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Assembly Language Interface 
A.1 Introduction 

When mixing MC68000 assembly language routines and compiled C routines, there 
are several things to be aware of 

• Registers and Return Values 

• Calling Sequence 

• Stack Probes 

With an understanding of these three topics, you should be able to write both C 
programs that call MC68000 assembly language routines and assembly language 
routines that call compiled C routines. 

A.1.1 Registers and Return Values 

Function return values are passed in registers if possible. The set of machine registers 
used is called the save set, and includes the registers from c/2-</7 and a2 -o7that are 
modified by a routine. The compiler assumes that these registers are preserved by the 
callee, and saves them itself when it is generating code for the callee (when a C 
compatible routine is called by another routine, we refer to the calling routine as the 
caller. We refer to the called routine as the callee.) Note that a6 and a7 are in effect 
saved by a link instruction at procedure entry . 

The function return value is in dO. The current floating point implementation returns 
the high order 32 bits of doubles in dl , and the low order 32 bits in dO. Functions that 
return structure values (not pointers to the values)dosoby loading d0 with a pointer to a 
static buffer containing the structure value. 

Thismakesthe following two functions equivalent: 

struct foo proc ()< 

struct foo this; 

return (this); 



struct foo *proc ()! 

struct foo this; 
static struct foo temp; 

temp = this; 
return (&temp); 

i 
i 

This implementation allows recursive reentrancy (as long as the explicit form is not 
used, since the first sequence is indivisible but not the second). However, this 
implementation does not permit multitasking reentrancy. Note that the latter includes 
the XENIX signalO)czll. 

SetjmpQ) and longjmpO) can not be implemented as they are on the PDP-11, 
because each procedure saves only the registers from the save set that it will modify. 
This makes it difficult to get back the current values of the register variables of the 
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bytes pushed as temporaries, save areas, and arguments by the whole procedure. The 
8 bytes are the space for the return address and frame pointer save (by the link 
instruction) of a nested call . The slop is tolerance so that extremely short runtimes that 
use little stack do not need to perform a stack probe. The tolerance is intentionally kept 
small to conserve memory, so make sure you understand what you are doing before 
you considerlcaving out a stack probe in your assembly procedures. 

In most cases, unless you are pushing huge structures or doing tricks with the stack 
within your procedure, you can use the following instruction foryour stack probe: 

tstb -KXHsp) 

This makes sure that enough space has been allocated for most of the usual things you 
might do with the stackandisenough for the XENIX runtimes that do not perform stack 
probes. Note that you do not need to consider space allocated by the link instruction in 
this stack probe, since it is already added by indexing off the stack pointer. 
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XENIX System Calls 



B.l Introduction 



This appendix lists some of the differences between XENIX 2.3, XENIX 3.0, UNIX 
V7, and UNIX System 3.0. It is intended to aid users who wish to convert system 
calls in existing application programs for use on other systems. 



B.2 Executable File Format 

Both XENIX 3.0 and UNIX System 3.0 execute only those programs with the 
x. out executable file format. The format is similar to the old «. out format, but 
contains additional information about the executable file, such as text and data 
relocation bases, target machine identification, word and byte ordering, and 
symbol table and relocation table format. The jr. out file also contains the 
revision number of the kernel which is used during execution to control access 
to system functions. To execute existing programs in a. out format, you must 
first convert to the x. out format. The format is described in detail in a. out(F) in 
the XENIX Reference Manual. 



B.3 Revised System Calls 

Some system calls in XENIX 3.0 and UNIX System 3.0 have been revised and do 
not perform the same tasks as the corresponding calls in previous systems. To 
provide compatibilty for old programs, XENIX 3.0 and UNIX System 3.0 
maintain both the new and the old system calls and automatically check the 
revision information in the jr. out header to determine which version of a system 
call should be made. The following table lists the revised system calls and their 
previous versions. 



System Call # 


XENIX 2.3 function 


Syst< 


;m 3 fun 


35 


ftime 




unused 


38 


unused 




clocal 


39 


unused 




setpgrp 


40 


unused 




cxenix 


57 


unused 




utssys 


62 


clocal 




fcntl 


63 


cxenix 




ulimit 



The cxenix function provides access to system calls unique to XENIX System 
3.0. The clocal function provides access to all calls unique to an OEM. 



B.4 Version 7 Additions 

XENIX 3.0 maintains a number of UNIX V7 features that were dropped from 
UNIX System 3.0. In particular, XENIX 3.0 continues to support the dup2 and 
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B.9 Separate Version Libraries 



XENIX 3.0 and UNIX System 3.0 support the construction of XENIX 2.3 
executable files. These systems maintain both the new and old versions of 
system calls in separate libraries and include files. 
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Name 

intro - Introduces XENIX Software Development commands. 

Description 

This section describes use of the individual commands available in 
the XENIX Software- Development System. Each individual com- 
mand is labeled with the letters CP to distinguish it from commands 
available in the XENIX Timesharing and Text Processing Systems. 
These letters are used for easy reference from other documentation. 
For example, the reference ec(CP) indicates a reference to a discus- 
sion of the cc command in this section, where the letter "C" stands 
for "command" and the letter "P" stands for "Programming". 



Syntax 



Unless otherwise noted, commands described in this section accept 
options and other arguments according to the following syntax: 



name [options] [cmdarg] 



where: 



name The filename or pathname of an executable file 

option A single letter representing a command option By con- 

vention, most options are preceded with a dash. 
Option letters can sometimes be grouped together as 
in - abed or alternatively they are specified individu- 
ally asin-a-b-c-d .The method of specifying 
options depends on the syntax of the individual com- 
mand. In the latter method of specifying options, 
arguments can be given to the options. For example, 
the - f option for many commands often takes a fol- 
lowing filename argument. 

emdarg A pathname or other command argument not begin- 

ning with a dash. It may also be a dash alone by itself 
indicating the standard input. 



See Also 

getopt(C), getopt(S) 

Diagnostics 

Upon termination, each command returns 2 bytes of status, one sup- 
plied by the system and giving the cause for termination, and (in the 
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Name 

adb - debugger 

Syntax 

adb [-w][ objfil [ corfil H 

Description 

Adb is a general purpose debugging program, it may be used to 
examine files and to provide a controlled environment for the exe- 
cution of XENIX programs. 

Objfil is normally an executable program file, preferably containing 
a symbol table; if not then the symbolic features of adb cannot be 
used although the file can still be examined. The default for objfil 
is a.out. Corfil is assumed to be a core image file produced after 
executing objfil; the default for corfil is core. 

Requests to adb are read from the standard input and responses are 
to the standard output. If the — w flag is present then both objfil 
and corfil are created if necessary and opened for reading and 
writing so that files can be modified using adb. Adb ignores 
QUIT; INTERRUPT causes return to the next adb command. 

In general requests to adb are of the form: 

f address | [ , count ] f command] [ ; | 

If address is present then dot is set to address. Initially dot is set 
to 0. For most commands count specifies how many times the 
command will be executed. The default count is 1. Address and 
count are expressions. 

The interpretation of an address depends on the context it is used 
in. If a subprocess is being debugged then addresses are inter- 
preted in the usual way in the address space of the subprocess. 
For further details of address mapping see ADDRESSES. 

EXPRESSIONS 

The value of dot. 

+ The value of dot incremented by the current increment. 

The value of dot decremented by the current increment. 

" The last address typed. 

integer If the integer begins with it is an an octal number. It is 
a hexadecimal number if preceded by Ox or OX. It is a 
decimal number when preceded by Od, 0D, Ot, or 0T; 
otherwise the current input radix (default decimal). 

'cccc' The ASCII value of up to 4 characters. \ may be used to 
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to the format/. 

// Locations starting at address in corfil are printed according 

to the format/. 

=/ The value of address itself is printed in the styles indi- 
cated by the format/. 

A format consists of one or more characters that specify a style of 
printing. Each format character may be preceded by a decimal 
integer that is a repeat count for the format character. While step- 
ping through a format dot is incremented temporarily by the 
amount given for each format letter. If no format is given then the 
last format is used. The format letters available are as follows. 

o 2 Print 2 bytes in octal. All octal numbers output 
by adb are preceded by 0. 

O 4 Print 4 bytes in octal. 

q 2 Print in signed octal. 

Q4 Print long signed octal. 

d 2 Print in decimal. 

D4 Print long decimal. 

x 2 Print 2 bytes in hexadecimal. All hexadecimal 
numbers output by adb are preceded by Ox. 

X 4 Print 4 bytes in hexadecimal. 

u 2 Print as an unsigned decimal number. 

U 4 Print long unsigned decimal. 

b 1 Print the addressed byte in octal. 

c 1 Print the addressed character. 

C i Print the addressed character using the following 
escape convention. Character values 000 to 040 
are printed as @ followed by the corresponding 
character in the range 0100 to 0140. The char- 
acter @ is printed as @@. 

s n Print the addressed characters until a zero char- 
acter is reached. 

S n Print a string using the @ escape convention, n 
is the length of the string including its zero ter- 
minator. 

Y 4 Print 4 bytes in date format (see ctlme(S)). 

i n Print as MC68000 instructions, n is the number 
of bytes occupied by the instruction. This style 
of printing causes variables 1 and 2 to be set to 
the offset parts of the source and destination 
respectively. 

a Print the value of dot in symbolic form. Symbols 
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! A shell is called to read the rest of the line following T. 

^modifier 

Miscellaneous commands. The available modifiers are: 

</ Read commands from the file /and return. 

>/ Send output to the file /, which is created if it 

does not exist; > ends the output diversion, 
r Print the general registers and the instruction 

addressed by pc. Dot is set to pc. 
b Print all breakpoints and their associated counts 

and commands, 
c C stack backtrace, if address is given then it is 

taken as the address of the current frame. 

(instead of a6). If count is given then only the 

first count frames are printed, 
e The names and values of external variables are 

printed. 
w Set the page width for output to address (default 

80). 
s Set the limit for symbol matches to address 

(default 255). 
o Set the current input radix to octal. 

d Set the current input radix to decimal. EXPRES- 

SIONS. 
x Set the current input radix to hexadecimal. 

q Exit from adb. 

v Print all non zero variables in hexadecimal. 

m Print the address map. 

'.modifier 

Manage a subprocess. Available modifiers are: 

be Set breakpoint at address. The breakpoint is 

executed count— I times before causing a stop. 
Each time the breakpoint is encountered the 
command c is executed, if this command sets 
dot to zero then the breakpoint causes a stop. 

d Delete breakpoint at address. 

r Run objfil as a subprocess. If address is given 

explicitly then the program is entered at this 
point; otherwise the program is entered at its 
standard entry point, count specifies how many 
breakpoints are to be ignored before stopping. 
Arguments to the subprocess may be supplied on 
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bl ^address <e2 —> file 

address ^address +J2—b2, 

otherwise, the requested address is not legal. In some cases (e.g., 
for programs with separated 1 and D space) the two segments for a 
file may overlap, if a ? or / is followed by an » then only the 
second triple is used. 

The initial setting of both mappings is suitable for normal a.out 
and core files, if either file is not of the kind expected then, for 
that file, bl is set to 0, el is set to the maximum file size and/7 is 
set to 0; in this way the whole file can be examined with no 
address translation. 

So that adb may be used on large files all appropriate values are 
kept as signed 32 bit integers. 

Files 

/dev/mem 
/dev/swap 
a.out 
core 

See Also 

ptrace(S), a.out(F), core(F) 

DIAGNOSTICS 

The message 'adb* when there is no current command or format. 
Comments about inaccessible files, syntax errors, abnormal termi- 
nation of commands, etc. 

Exit status is 0, unless last command failed or returned nonzero 
status. 

Notes 

A breakpoint set at the entry point is not effective on initial entry to 

the program. 

When single stepping, system calls do not count as an executed 

instruction. 

Local variables whose names are the same as an external variable 

may foul up the accessing of the external. 
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- rrel The release into which the initial delta is inserted. 

This option may be used only if the — i option is 
also used. If the - r option is not used, the initial 
delta is inserted into release 1. The level of the ini- 
tial delta is always 1 (by default initial deltas are 
named 1.1). 

- t[name] The name of a file from which descriptive text for 

the SCCS file is to be taken. If the - t option is 
used and admin is creating a new SCCS file (the - n 
and/or - i options also used), the descriptive text 
filename must also be supplied. In the case of exist- 
ing SCCS files: a - t option without a filename 
causes removal of descriptive text (if any) currently 
in the SCCS file, and a - t option with a filename 
causes text (if any) in the named file to replace the 
descriptive text (if any) currently in the SCCS file. 

- (flag This option specifies a flag, and possibly a value for 

the flag, to be placed in the SCCS file. Several f 
options may be supplied on a single admin com- 
mand line. The allowable flags and their values are: 

b Allows use of the - b option on a get(CP) 

command to create branch deltas. 

cetU The highest release (i.e., "ceiling"), a number 
less than or equal to 9999, which may be 
retrieved by a get{CP) command for editing. 
The default value for an unspecified c flag is 
9999. 

(floor The lowest release (i.e., "floor"), a number 
greater than but less than 9999, which may 
be retrieved by a get[CP) command for edit- 
ing. The default value for an unspecified f flag 
is 1. 

dSID The default delta number (SID) to be used by 
a get(CP) command. 

i Causes the "No id keywords (ge6)" message 

issued by get(CP) or delta(CP) to be treated as 
a fatal error. In the absence of this flag, the 
message is only a warning. The message is 
issued if no SCCS identification keywords (see 
get(CP)) are found in the text retrieved or 
stored in the SCCS file. 

j Allows concurrent get(CP) commands for edit- 

ing on the same SID of an SCCS file. This 
allows multiple concurrent updates to the same 
version of the SCCS file. 
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- alogin 



- el o gin 



- y[ comment 



lliet A list of releases to be "unlocked". See the 
- f option for a description of the 1 flag and 
the syntax of a liet 

A login name, or numerical XENIX group ID, to be 
added to the list of users which may make deltas 
(changes) to the SCCS file. A group ID is equivalent 
to specifying all login names common to that group 
ID. Several a options may be used on a single 
admin command line. As many logins, or numerical 
group IDs, as desired may be on the list simultane- 
ously. If the list of users is empty, then anyone 
may add deltas. 

A login name, or numerical group ID, to be erased 
from the list of users allowed to make deltas 
(changes) to the SCCS file. Specifying a group ID is 
equivalent to specifying all login names common to 
that group ID. Several e options may be used on a 
single admin command line. 

The comment text is inserted into the SCCS file as a 
comment for the initial delta in a manner identical 
to that of delta(CP). Omission of the - y option 
results in a default comment line being inserted in 
the form: 



- m[mrft«f] 



- h 



YY/MMjDD HH:MM:SS by login 

The - y option is valid only if the - i and/or - n 
options are specified (i.e., a new SCCS file is being 
created). 

The list of Modification Requests (MR) numbers is 
inserted into the SCCS file as the reason for creating 
the initial delta in a manner identical to delta(CP). 
The v flag must be set and the MR numbers are 
validated if the v flag has a value (the name of an 
MR number validation program). Diagnostics will 
occur if the v flag is not set or MR validation fails. 

Causes admin to check the structure of the SCCS file 
(see eccefUe(F)) , and to compare a newly computed 
checksum (the sum of all the characters in the SCCS 
file except those in the first line) with the checksum 
that is stored in the first line of the SCCS file. 
Appropriate error diagnostics are produced. 

This option inhibits writing on the file, nullifying 
the effect of any other options supplied, and is 
therefore only meaningful when processing existing 
files. 
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Name 

ax - Maintains archives and libraries. 

Syntax 

ar key [ posname ] afile name ... 

Description 

ar maintains groups of files combined into a single archive file. Its 
main use is to create and update library files as used by the link edi- 
tor, though it can be used for any similar purpose. 

When ar creates an archive, it always creates the header in the for- 
mat of the local system. 

Key is one character from the set drqtpmx, optionally concatenated 
with one or more of vuaibcl. afile is the archive file. The namet are 
constituent files in the archive file. The meanings of the key charac- 
ters are: 

d Deletes the named files from the archive file. 

r Replaces the named files in the archive file. If the optional 
character u is used with r, then only those files with modified 
dates later than the archive files are replaced. If an optional 
positioning character from the set abi is used, then the posname 
argument must be present and specifies that new files are to be 
placed after (a) or before (bor i) posname. Otherwise new files 
are placed at the end. 

q Quickly appends the named files to the end of the archive file. 
Optional positioning characters are invalid. The command does 
not check whether the added members are already in the 
archive. Useful only to avoid quadratic behavior when creating 
a large archive piece by piece. 

t Prints a table of contents of the archive file. If no names are 
given, all files in the archive are tabled. If names are given, 
only those files are tabled. 

p Prints the named files in the archive. 

m Moves the named files to the end of the archive. If a position- 
ing character is present, then the posname argument must be 
present and, as in r, specifies where the files are to be moved. 

x Extracts the named files. If no names are given, all files in the 
archive are extracted. In neither case does x alter the archive 
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Name 

as — assembler 

Syntax 

as [ -1 1 [ -o objfile ] f -g | files 

Description 

As assembles the named file, if the argument —1 is used, an 
assembly listing is produced and written to file.L. This includes the 
source, the assembled code, and any assembly errors. 

The output of the assembly is left on the file objfile; if that is 
omitted, file.o is used. If the optional -g flag is given, undefined 
symbols will be treated as externals. Arguments may appear in 
any order, except that -o must immediatly precede objfile. The 
optional flag — e (externals only) prevents local symbols from being 
extended into objfile' s symbol table. 

Files 

/tmp/A68tmpr* temporary 

See Also 

ld(CP), nm(CP), adb(CP), a.out(F) 
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Name 

cc - C compiler 

Syntax 

cc f option 1 ... file ... 

Description 

Cc is the XENIX M68000 C compiler. Arguments whose names 
end with '.c' are taken to be C source programs; they are com- 
piled, and each object program is left on the file whose name is 
that of the source with \o' substituted for \c\ The \o' file is 
normally deleted, however, if a single C program is compiled and 
loaded all at one go. 

In the same way, arguments whose names end with '.s* are taken 
to be assembly source programs and are assembled, producing a 
\o* file. 

The following options are interpreted by cc. See W(CP) for 
load— time options. 

— c Suppress the loading phase of the compilation, and force 

an object file to be produced even if only one program is 
compiled. 

-O Invoke an object— code optimizer. 

-S Compile the named C programs, and leave the 

assembler-language output on corresponding files 
suffixed \s\ 

— o output 

Name the final output file output. If this option is used 
the file 'a.out' will be left undisturbed. 

—Dname=def 

-Dname Define the name to the preprocessor, as if by '#define\ 
If no definition is given, the name is defined as 1 . 

-U/iame Remove any initial definition of name. 

-Idir 4 #include' files whose names do not begin with V are 
always sought first in the directory of the file argument, 
then in directories named in —I options, then in direc- 
tories on a standard list. 

-tl replace the compiler phase with a program called c68 
from the current directory. 

— 12 replace the object code optimizer phase with a program 
called c68o from the current directory. 
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Name 

cdc - Changes the delta commentary of an SCCS delta. 

Syntax 

cdc - rSID [- m[mrlist]] [- y( comment]] files 

Description 

Cdc changes the delta commentary for the SID specified by the — r 
option, of each named SCCS file. 

Delta commentary is defined to be the Modification Request (MR) 
and comment information normally specified via the delta(CP) com- 
mand (- m and - y options). 

If a directory is named, cdc behaves as though each file in the direc- 
tory were specified as a named file, except that nonSCCS files (last 
component of the pathname does not begin with s.) and unreadable 
files are silently ignored. If a name of - is given, the standard input 
is read (see Warning); each line of the standard input is taken to be 
the name of an SCCS file to be processed. 

Arguments to cdc, which may appear in any order, consist of options 
and file names. 

All the described options apply independently to each named file: 

- rSID Used to specify the SCCS /Dentification {SID) 

string of a delta for which the delta commen- 
tary is to be changed. 

- m[mrf»*f] If the SCCS file has the v flag set (see 

orfraw(CP)) then a list of MR numbers to be 
added and/or deleted in the delta commentary 
of the SID specified by the - r option may be 
supplied. A null MR list has no effect 

MR entries are added to the list of MRs in the 
same manner as that of delta(CP). In order to 
delete an MR, precede the MR number with 
the character ! (see Examples). If the MR to 
be deleted is currently in the list of MRs, it is 
removed and changed into a "comment" line. 
A list of all deleted MRs is placed in the com- 
ment section of the delta commentary and pre- 
ceded by a comment line stating that they were 
deleted. 
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The following interactive sequence does the same thing, 
cdc - rl.6 s.file 

MRs? !bl77-54321 M78-12345 H79-00001 
comments? trouble 

Warning 

If SCCS file names are supplied to the edc command via the standard 
input (- on the command line), then the - m and - y options must 
also be used. 



Files 

x-file See delta{ CP) 
z-file See delta{CP) 

See Also 

admin(CP), delta(CP), get(CP), help(CP), prs(CP), sccsfile(F) 

Diagnostics 

Use kelp(CP) for explanations. 
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- s This argument causes comb to generate a shell procedure 

that will produce a report for each file giving the filename, 
size (in blocks) after combining, original size (also in 
blocks), and percentage change computed by: 

100 * (original - combined) / original 

Before any SCCS files are actually combined, you should use this 
option to determine exactly how much space is saved by the combin- 
ing process. 

If no options are specified, comb will preserve only leaf deltas and 
the minimal number of ancestors needed to preserve the tree. 



Files 

comb????? Temporary files 

See Also 

admin(CP), delta(CP), get(CP), help(CP), prs(CP), sccsfile(F) 

Diagnostics 

Use Ae/p(CP) for explanations. 



Notes 



Comb may rearrange the shape of the tree of deltas. It may not save 
any space; in fact, it is possible for the reconstructed file to be larger 
than the original. 
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There are certain drivers that may be provided with the system, that 
are actually pseudo-device drivers; that is, there is no real hardware 
associated with the driver. Drivers of this type are identified on 
their respective manual entries. 



Second Part of dfile 

The second part contains three different types of lines. Note that all 
specifications of this part are required, although their order is arbi- 
trary. 

1. Root/pipe device specification 

Each line has three fields: 

root devname minor 

pipe devname minor 

where minor is the minor device number (in octal). 

2. Swap device specification 

One line that contains five fields as follows: 

swap devname minor swplo nswap 

where ewplo is the lowest disk block (decimal) in the swap area and 
nswap is the number of disk blocks (decimal) in the swap area. 

3. Parameter specification 

A number of lines of two fields each as follows (number is decimal): 



buffers 


number 


inodes 


number 


files 


number 


mounts 


number 


swapmap 


number 


pages 


number 


calls 


number 


procs 


number 


maxproc 


number 


texts 


number 


clists 


number 


locks 


number 


timezone 


number 


daylight 


Oor 1 


Ex ample 





Suppose we wish to configure a system with the following devices: 
one HD disk drive controller with 1 drive 
one FD floppy disk drive controller with 1 driver 
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Diagnostics 

Diagnostics are routed to the standard output and are self- 
explanatory. 



Notes 



The - t option does not know about devices that have aliases. How- 
ever, the major device numbers are always correct 
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n Omits column 4 (no context) 

Uses an only file (see above) 

s Current symbol in column 3 (default) 

t User-supplied temporary file 

u Prints only symbols that occur exactly once 

x Prints only C external symbols 

1 Sorts output on column 1 (default) 

2 Sorts output on column 2 

3 Sorts output on column 3 

Files 

/usr/lib/cref/* Assembler specific files 

See Also 

as( CP) , cc( CP) , sort( C) , xref( CP) 



Notes 



Cref inserts an ASCII DEL character into the intermediate file after 
the eighth character of each name that is eight or more characters 
long in the source file. 
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Credit 

This utility was developed at the University of California at Berkeley 
and is used with permission. 
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- fJLiet Specifies a list (see 0ef(CP) for the definition of lift) 

of deltas which are to be ignored when the file is 
accessed at the change level (SID) created by this 
delta. 

- m[mrf»*<] If the SCCS file has the v flag set (see admin(CP)) 

then a Modification Request (MR) number must be 
supplied as the reason for creating the new delta. 

If - m is not used and the standard input is a termi- 
nal, the prompt MRs? is issued on the standard out- 
put before the standard input is read; if the standard 
input is not a terminal, no prompt is issued. The 
MRs? prompt always precedes the comments? 
prompt (see - y keyletter). 

MRs in a list are separated by blanks and/or tab 
characters. An unescaped newline character ter- 
minates the MR list. 

Note that if the v flag has a value (see arfmt'n(CP)), 
it is taken to be the name of a program (or shell 
procedure) which will validate the correctness of the 
MR numbers. If a nonzero exit status is returned 
from MR number validation program, delta ter- 
minates (it is assumed that the MR numbers were 
not all valid). 

- y[ comment] Arbitrary text used to describe the reason for mak- 

ing the delta. A null string is considered a valid 
comment 

If - y is not specified and the standard input is a 
terminal, the prompt comments? is issued on the 
standard output before the standard input is read; if 
the standard input is not a terminal, no prompt is 
issued. An unescaped newline character terminates 
the comment text. 

- p Causes delta to print (on the standard output) the 

SCCS file differences before and after the delta is 
applied. Differences are displayed in a diff{C) for- 
mat. 



Files 

All files of the form ?-file are explained in Chapter 5, "SCCS: A 
Source Code Control System" in the XENIX Programmer's Guide. The 
naming convention for these files is also described there. 

g-file Existed before the execution of delta; removed after 

completion of delta. 
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Name 

get - Gets a version of an SCCS file. 



Syntax 



get [- rSID] (- ccutoff] [- ilistl [- xlist] (- aseq-no.j [- k) [- e] 
[- l[p|] [- p] j- ml [- n) [- s] [- bj [- gj |- t) file ... 



Description 

Get generates an ASCII text file from each named SCCS file according 
to the specifications given by its options, which begin with — . The 
arguments may be specified in any order, but all options apply to all 
named SCCS files. If a directory is named, get behaves as though 
each file in the directory were specified as a named file, except that 
nonSCCS files (last component of the pathname does not begin with 
s.) and unreadable files are silently ignored. If a name of - is 
given, the standard input is read; each line of the standard input is 
taken to be the name of an SCCS file to be processed. Again, 
nonSCCS files and unreadable files are silently ignored. 

The generated text is normally written into a file called the g-fUe 
whose name is derived from the SCCS filename by simply removing 
the leading s.; (see also FILES, below). 

Each of the options is explained below as though only one SCCS file 
is to be processed, but the effects of any option apply independently 
to each named file. 

- rSID The SCCS /Identification string (SID) of the version 

(delta) of an SCCS file to be retrieved. 

- ccutoff Cutoff date-time, in the form: 

YY[MM[DD[HH[MM[SS]j]]] 

No changes (deltas) to the SCCS file that were created 
after the specified cutoff date-time are included in the 
generated ASCII text file. Units omitted from the date- 
time default to their maximum possible values; that is, 
- c7502 is equivalent to - c750228235950. Any number 
of nonnumeric characters may separate the various 2 
digit pieces of the cutoff date-time. This feature allows 
you to specify a cutoff date in the form: "- c77/2/2 
9:22:25". 

- e Indicates that the get is for the purpose of editing or 

making a change (delta) to the SCCS file via a subsequent 
use of delta (CP). The - e option used in a get for a par- 
ticular version (SID) of the SCCS file prevents further 
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- s Suppresses all output normally written on the standard 

output. However, fatal error messages (which always go 
to file descriptor 2) remain unaffected. 

- m Causes each text line retrieved from the SCCS file to be 

preceded by the SID of the delta that inserted the text 
line in the SCCS file. The format is: SID, followed by a 
horizontal tab, followed by the text line. 

- n Causes each generated text line to be preceded with the 

9?M% identification keyword value (see below). The for- 
mat is: 92M% value, followed by a horizontal tab, fol- 
lowed by the text line. When both the - m and - n 
options are used, the format is: 9?M% value, followed by 
a horizontal tab, followed by the - m option generated 
format. 

- g Suppresses the actual retrieval of text from the SCCS file. 

It is primarily used to generate an l-file, or to verify the 
existence of a particular SID. 

- t Used to access the most recently created (top) delta in a 

given release (e.g., - rl), or release and level (e.g., 
- rl.2). 

- aaeq-no. The delta sequence number of the SCCS file delta (ver- 

sion) to be retrieved (see eceefile(F)). This option is 
used by the comb( CP) command; it is not particularly 
useful should be avoided. If both the - r and - a 
options are specified, the - a option is used. Care 
should be taken when using the — a option in conjunc- 
tion with the - e option, as the SID of the delta to be 
created may not be what you expect. The - r option can 
be used with the - a and - e options to control the nam- 
ing of the SID of the delta to be created. 

For each file processed, get responds (on the standard output) with 
the SID being accessed and with the number of lines retrieved from 
the SCCS file. 

If the - e option is used, the SID of the delta to be made appears 
after the SID accessed and before the number of lines generated. If 
there is more than one named file or if a directory or standard input 
is named, each filename is printed (preceded by a newline) before it 
is processed. If the - i option is used included deltas are listed fol- 
lowing the notation "Included"; if the - x option is used, excluded 
deltas are listed following the notation "Excluded". 



Identification Keywords 

Identifying information is inserted into the text retrieved from the 
SCCS file by replacing identification keywords with their value 
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implied, the g-file's mode is 644; otherwise the mode is 444. Only 
the real user need have write permission in the current directory. 

The 1-fUe contains a table showing which deltas were applied in gen- 
erating the retrieved text. The l-file is created in the current direc- 
tory if the - 1 option is used; its mode is 444 and it is owned by the 
real user. Only the real user need have write permission in the 
current directory. 

Lines in the 1-fUe have the following format: 

a. A blank character if the delta was applied; 

* otherwise 

b. A blank character if the delta was applied or wasn't applied 
and ignored; 

* if the delta wasn't applied and wasn't ignored 

c. A code indicating a "special" reason why the delta was or 
was not applied: 

"I": Included 

"X": Excluded 

"C": Cut off (by a - c option) 

d. Blank 

e. SCCS identification (SID) 

f. Tab character 

g. Date and time (in the form YY/MM/DD HH:MM:SS) of crea- 
tion 

h. Blank 

i. Login name of person who created delta 

The comments and MR data follow on subsequent lines, indented 
one horizontal tab character. A blank line terminates each entry. 

The p-file is used to pass information resulting from a get with an 
- e option along to delta. Its contents are also used to prevent a 
subsequent execution of get with an - e option for the same SID 
until delta is executed or the joint edit flag, j, (see adtmn(CP)) is set 
in the SCCS file. The p-file is created in the directory containing the 
SCCS file and the effective user must have write permission in that 
directory. Its mode is 644 and it is owned by the effective user. The 
format of the p-file is: the gotten SID, followed by a blank, followed 
by the SID that the new delta will have when it is made, followed by 
a blank, followed by the login name of the real user, followed by a 
blank, followed by the date-time the get was executed, followed by a 
blank and the — i option if it was present, followed by a blank and 
the - x option if it was present, followed by a newline. There can 
be an arbitrary number of lines in the p-file at any time; no two lines 
can have the same new delta SID. 

The z-file serves as a lock-out mechanism against simultaneous 
updates. Its contents are the binary (2 bytes) process ID of the com- 
mand (i.e., get) that created it. The z-file is created in the directory 
containing the SCCS file for the duration of get. The same protection 
restrictions as those for the p-file apply for the z-file. The z-file is 
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Name 

gets - Gets a string from the standard input 

Syntax 

gete [ string J 



Description 

Gets can be used with e«A(CP) to read a string from the standard 
input. If etring is given it is used as a default value if an error 
occurs. The resulting string (either string or as read from the stan- 
dard input) is written to the standard output. If no string is given 
and an error occurs, gets exits with exit status 1. 



See Also 

line(C), csh(CP) 
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- d Causes the data relocation records to be printed out. 

- t Causes the text relocation records to be printed out 

- r Causes both text and data relocation to be printed. 

- p Causes seek positions to be printed out as defined by macros in 

the include file, <a.out.h>. 

- s Prints the symbol table. 

- S Prints the file segment table with a header. (Only applicable to 

x.out segmented executable files.) 

See Also 

a.out(F), nm(CP) 
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Name 

Id - link editor 

Syntax 

Idf option] file ... 

Description 

Ld combines several object programs into one, resolves external 
references, and searches libraries. Ld combines the given object 
files, producing an object module which can be either executed or 
become the input for a further Id run (in the latter case, the — r 
option must be given to preserve the relocation records). The 
output of Id is left by default in the file x.out. This file is made 
executable only if no errors occurred. 

The files given as arguments are concatenated in the order 
specified. The default entry point of the output is the beginning of 
the first routine in the first file. The C compiler, cc , calls Id 
automatically unless given the — c option. The command line that 
cc passes to Id is 

ld /lib/crtO.o files cc— options -lc 

If any argument is a library, it is searched exactly once at the point 
it is encountered in the argument list. Only those routines defining 
an unresolved external reference are loaded, if a routine from a 
library references another routine in the library, and the library has 
not been processed by ranlib(CP), the referenced routine must 
appear after the referencing routine in the library. Thus the order 
of programs within libraries may be important. If the first member 
of a library is named '_ .SYMDEF', then it is understood to be a 
dictionary for the library 

as produced by ranlib; the dictionary is searched iteratively to 
satisfy as many references as possible. 

The symbols '_etext\ 'jedata' and '_end' ('etext', 'edata' and 'end' 
in Q are reserved, and if referred to, are set to the first location 
above the program, the first location above initialized data, and the 
first location above all data, respectively. It is erroneous to define 
these symbols. 

If no errors occur and there are no unresolved external references, 
then short form relocation information is attached and the file is 
made executable. This short form relocation information is 
sufficient to allow the file to be used for another pass of Id , to 
change the text and data base addresses. At the same time, the — n 
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symbol table; only enter external symbols. This option 
saves some space in the output file. 

—X Save local symbols except for those whose names begin 
with *L\ This option is used by cc (CP) to discard inter- 
nally generated labels while retaining symbols local to 
routines. 

-r Generate (long form) relocation records in the output file 
so that the output file can be the subject of another Id run. 
This flag also prevents final definitions from being given 
to common symbols and suppresses the 'undefined sym- 
bol' diagnostics. 

— d Force definition of common storage even if the — r flag is 
present. 

— nn Arrange that when the output file is executed, the text 
portion will be read— only and shared among all users 
executing the file. This involves moving the data areas up 
to the first possible page boundary following the end of 
the text. A warning is issued if the current machine does 
not support this option. 

Identical to — nn except that the text and data positions are 
reversed. 



— nr 



— n Identical to whichever of -nn and — nr is the default for 
the current machine. 

— i When the output file is executed, the program text and 

data areas are given separate address spaces. The only 
difference between this option and — n is that with -i the 
data may start at a boundary unrelated to the position of 
the text. A warning is issued if the current machine does 
not support this option. 

-o The name argument after -o is used as the name of the Id 
output file, instead of x.out 

— e The following argument is taken to be the name of the 
entry point of the loaded program. The base of the text 
segment is the default. 

— D The next argument is a decimal number that sets the size 
of the data segment. 

— N The next argument is taken to be a hexadecimal number 
that sets the pagesize, or rounding size, for use with the 
— n option. With — i, it specifies the base of the data 
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Name 

lex - Generates programs for lexical analysis. 



Syntax 

lex [- ctvn] [ file ] ... 

Description 

Lex generates programs to be used in simple lexical analysis of text 

The input fUe$ (standard input default) contain strings and expres- 
sions to be searched for, and C text to be executed when strings are 
found. 

A file lex.yy.c is generated which, when loaded with the library, 
copies the input to the output except when a string specified in the 
file is found; then the corresponding program text is executed. The 
actual string matched is left in yytext, an external character array. 
Matching is done in order of the strings in the file. The strings may 
contain square brackets to indicate character classes, as in [abx- z] 
to indicate a, b, x, y, and z; and the operators *, +, and ? mean 
respectively any nonnegative number of, any positive number of, 
and either zero or one occurrences of, the previous character or 
character class. The character . is the class of all ASCII characters 
except newline. Parentheses for grouping and vertical bar for alter- 
nation are also supported. The notation r{d,e} in a rule indicates 
between d and t instances of regular expression r. It has higher pre- 
cedence than I but lower than *, f, + , and concatenation. The 
character * at the beginning of an expression permits a successful 
match only immediately after a newline, and the character % at the 
end of an expression requires a trailing newline. The character / in 
an expression indicates trailing context; only the part of the expres- 
sion up to the slash is returned in yytext, but the remainder of the 
expression must follow in the input stream. An operator character 
may be used as an ordinary symbol if it is within " symbols or pre- 
ceded by \. Thus [a- zA- Z]+ matches a string of letters. 

Three subroutines defined as macros are expected: inputQ to read a 
character; unput(c) to replace a character read; and output(e) to 
place an output character. They are defined in terms of the standard 
streams, but you can override them. The program generated is 
named yylex(), and the library contains a mainQ which calls it. The 
action REJECT on the right side of the rule causes this match to be 
rejected and the next suitable match executed; the function 
yymoreQ accumulates additional characters into the same yytext; and 
the function yyless(p) pushes back the portion of the string matched 
beginning at p, which should be between yytext and yytext+ yyleng. 
The macros input and output use files yyin and yyout to read from 
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number of transitions is % (3000) 

The use of one or more of the above automatically implies the — v 
option, unless the - n option is used. 



See Also 

yacc(CP) 

Xenix Software Development Guide 



March 26, 1884 Page 3 



L1NT{CP) L1NT{CP) 

The following arguments alter lint's behavior 

- n Does not check compatibility against either the standard or the 

portable lint library. 

- p Attempts to check portability to other dialects of C. 

- Uibname 

Checks functions definitions in die specified lint library. For 
example, - lm causes the library Uibnuln to be checked. 

The - D, - U, and - I options of ee(CP) are also recognized as 
separate arguments. 

Certain conventional comments in the C source will change the 
behavior of lint: 

/*NOTREACHED*/ 

At appropriate points stops comments about unreachable 
code. 

/♦VARARGSn*/ 

Suppresses the usual checking for variable numbers of argu- 
ments in the following function declaration. The data types 
of the first n arguments are checked; a missing it is taken to 
beO. 

/♦ARGSUSED*/ 

Turns on the - v option for the next function. 

/♦LINTLIBRARY*/ 

Shuts off complaints about unused functions in this file. 

Lint produces its first output on a per source file basis. Complaints 
regarding included files are collected and printed after all source files 
have been processed. Finally, information gathered from all input 
files is collected and checked for consistency. At this point, if it is 
not clear whether a complaint stems from a given source file or from 
one of its included files, the source filename will be printed followed 
by a question mark. 

Files 

/usr/lib/lint[12] Program files 

/usr/lib/llibc.ln, /usr/lib/llibport.ln, /usr/lib/llibm.ln, 

/usr/lib/llibdbm.ln, /usr/lib/llibtermlib.ln 

Standard lint libraries (binary format) 
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Name 

lorder - Finds ordering relation for an object library. 

Syntax 

lorder file ... 



Description 

Lorder creates an ordered listing of object filenames, showing which 
files depend on variables declared in other files. The file is one or 
more object or library archive files (see «r(CP)). The standard out- 
put is a list of pairs of object filenames. The first file of the pair 
refers to external identifiers defined in the second. The output may 
be processed by teort(CP) to find an ordering of a library suitable for 
one-pass access by ld(CP). 



Example 

The following command builds a new library from existing ,o files: 
ar cr library s lorder *.o |tsort N 

Files 

*symref, *symdef Temp files 

See Also 

ar(CP), ld(CP), teort(CP) 



Notes 



Object files whose names do not end with .o, even when contained 
in library archives, are overlooked. Their global symbols and refer- 
ences are attributed to some other file. 
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Macro Calls 

Macro calls have the form: 

name(argl,arg2, ..., argn) 

The ( must immediately follow the name of the macro. If a defined 
macro name is not followed by a (, it is deemed to have no argu- 
ments. Leading unquoted blanks, tabs, and newlines are ignored 
while collecting arguments. Potential macro names consist of alpha- 
betic letters, digits, and underscore _, where the first character is not 
a digit 

Left and right single quotation marks are used to quote strings. The 
value of a quoted string is the string stripped of the quotation marks. 

When a macro name is recognized, its arguments are collected by 
searching for a matching right parenthesis. Macro evaluation 
proceeds normally during the collection of the arguments, and any 
commas or right parentheses which happen to turn up within the 
value of a nested call are as effective as those in the original input 
text. After argument collection, the value of the macro is pushed 
back onto the input stream and rescanned. 

M4 makes available the following built-in macros. They may be 
redefined, but once this is done the original meaning is lost Their 
values are null unless otherwise stated. 

define The second argument is installed as the value of the 

macro whose name is the first argument Each 
occurrence of $n in the replacement text, where n is a 
digit, is replaced by the n-th argument Argument is 
the name of the macro; missing arguments are replaced 
by the null string; $£ is replaced by the number of 
arguments; $* is replaced by a list of all the arguments 
separated by commas; $9 is like $*, but each argument 
is quoted (with the current quotation marks). 

undefine Removes the definition of the macro named in its argu- 
ment 

defn Returns the quoted definition of its arguments). It is 

useful for renaming macros, especially built-ins. 

pushdef Like define, but saves any previous definition. 

popdef Removes current definition of its arguments), expos- 

ing the previous one if any. 

ifdef If the first argument is defined, the value is the second 

argument, otherwise the third. If there is no third 
argument, the value is null. The word XENIX is 
predefined in M4- 
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radix for the result; the default is 10. The third argu- 
ment may be used to specify the minimum number of 
digits in the result. 

len Returns the number of characters in its argument. 

index Returns the position in its first argument where the 

second argument begins (zero origin), or - 1 if the 
second argument does not occur. 

substr Returns a substring of its first argument. The second 

argument is a zero origin number selecting the first 
character; the third argument indicates the length of 
the substring. A missing third argument is taken to be 
large enough to extend to the end of the first string. 

translit Transliterates the characters in its first argument from 

the set given by the second argument to the set given 
by the third. No abbreviations are permitted. 

include Returns the contents of the file named in the argu- 

ment. 

sinclude Identical to include, except that it says nothing if the 

file is inaccessible. 

syscmd Executes the XENIX command given in the first argu- 

ment. No value is returned. 

sysval Is the return code from the last call to tytcmi. 

maketemp Fills in a string of XXXXX in its argument with the 
current process ID. 

m4exit Causes immediate exit from m^. Argument 1, if given, 

is the exit code; the default is 0. 

m4wrap Argument 1 will be pushed back at final EOF; example: 

m4wrap(' v cleanup( ) *\ 

errprint Prints its argument on the diagnostic output file. 

dumpdef Prints current names and definitions, for the named 
items, or for all if no arguments are given. 

traceon With no arguments, turns on tracing for all macros 

(including built- ins). Otherwise, turns on tracing for 
named macros. 

traceoff Turns off trace globally and for any macros specified. 

Macros specifically traced by traceon can be untraced 
only by specific calls to tract off. 
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- q Question. The make command returns a zero or 

nonzero status code depending on whether the target 
file is or is not up-to-date. 

.DEFAULT If a file must be made but there are no explicit com- 
mands or relevant built-in rules, the commands associ- 
ated with the name .DEFAULT are used if it exists. 

.PRECIOUS Dependents of this target will not be removed when 
quit or interrupt are hit. 

.SILENT Same effect as the - s option. 

.IGNORE Same effect as the - i option. 

Make executes commands in makefile to update one or more target 
namee. Name is typically a program. If no - f option is present, 
makefile, Makefile, s. makefile, and s. Makefile are tried in order. 
If makefile is - , the standard input is taken. More than one — f 
makefile argument pair may appear. 

Make updates a target only if it depends on files that are newer than 
the target. All prerequisite files of a target are added recursively to 
the list of targets. Missing files are deemed to be out of date. 

Makefile contains a sequence of entries that specify dependencies. 
The first line of an entry is a blank-separated, nonnull list of targets, 
then a :, then a (possibly null) list of prerequisite files or dependen- 
cies. Text following a ; and all following lines that begin with a tab 
are shell commands to be executed to update the target. The first 
line that does not begin with a tab or £ begins a new dependency or 
macro definition. Shell commands may be continued across lines 
with the < backslash ><newline> sequence. (#) and newline sur- 
round comments. 

The following makefile says that pgm depends on two files a.o and 
b.o, and that they in turn depend on their corresponding source files 
(a.c and b.c) and a common file incl.h: 

pgm: a.o b.o 

cc a.o b.o - o pgm 
a.o: incl.h a.c 

cc - c a.c 
b.o: incl.h b.c 

cc - c b.c 

Command lines are executed one at a time, each by its own shell. A 
line is printed when it is executed unless the - s option is present, 
or the entry .SILENT: is in makefile, or unless the first character of 
the command is @ . The - n option specifies printing without execu- 
tion; however, if the command line has the string $(MAKE) in it, the 
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eubetS. Strings (for the purposes of this type of substitution) are 
delimited by blanks, tabs, newline characters, and beginnings of 
lines. An example of the use of the substitute sequence is shown 
under Libraries. 



Internal Maeroe 

There are five internally maintained macros which are useful for 
writing rules for building targets: 

$* The macro $* stands for the filename part of the current 
dependent with the suffix deleted. It is evaluated only for 
inference rules. 

$Q The $0 macro stands for the full target name of the current 
target. It is evaluated only for explicitly named dependencies. 

$< The $< macro is only evaluated for inference rules or the 
•DEFAULT rule. It is the module which is out of date with 
respect to the target (i.e., the "manufactured" dependent 
filename). Thus, in the .c.o rule, the $< macro would evalu- 
ate to the .c file. An example for making optimized .o files 
from .c files is: 

.c.o: 

cc - c - O $*.c 



.c.o: 

cc - c - O $< 

$? The $? macro is evaluated when explicit rules from the 
makefile are evaluated. It is the list of prerequisites that are 
out of date with respect to the target; essentially, those 
modules which must be rebuilt. 

$% The %% macro is only evaluated when the target is an archive 
library member of the form lib(file.o). In this case, $Q evalu- 
ates to lib and $%evaluates to the library member, file.o. 

Four of the five macros can have alternative forms. When an upper 
case D or F is appended to any of the four macros the meaning is 
changed to "directory part" for D and "file part" for F. Thus, 
$(@ D) refers to the directory part of the string $@ . If there is no 
directory part ./ is generated. The only macro excluded from this 
alternative form is $?. 



Suffixes 

Certain names (for instance, those ending with .o) have default 
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This is because make has a set of internal rules for building files. 
The user may add rules to this list by simply putting them in the 
makefile. 

Certain macros are used by the default inference rules to permit the 
inclusion of optional matter in any resulting commands. For exam- 
ple, CFLAGS, LFLAGS, and YFLAGS are used for compiler options to 
ee(CP), lex(CP), and yaee(CP) respectively. Again, the previous 
method for examining the current rules is recommended. 

The inference of prerequisites can be controlled. The rule to create 
a file with suffix .o from a file with suffix .c is specified as an entry 
with .c.o: as the target and no dependents. Shell commands associ- 
ated with the target define the rule for making a .o file from a .c file. 
Any target that has no slashes in it and starts with a dot is identified 
as a rule and not as a true target. 



Lxbrariet 

If a target or dependency name contains parentheses, it is assumed 
to be an archive library, the string within parentheses referring to a 
member within the library. Thus lib(file.o) and $(LIB)(file.o) both 
refer to an archive library which contains file.o. (This assumes the 
LIB macro has been previously defined.) The expression 
$(LIB)(filel.o file2.o) is not legal. Rules pertaining to archive 
libraries have the form .XX.a where the XX is the suffix from which 
the archive member is to be made. An unfortunate byproduct of the 
current implementation requires the XX to be different from the 
suffix of the archive member. Thus, one cannot have lib( file.o) 
depend upon file.o explicitly. The most common use of the archive 
interface follows. Here, we assume the source files are all C type 
source: 

lib: lib(filel.o) Iib(file2.o) Hb(file3.o) 

©echo lib is now up to date 
.c.a: 

$(CC) - c $(CFLAGS) $< 

ar rv $@ $*.o 

rm -f $*.o 

In fact, the .c.a rule listed above is built into make and is unneces- 
sary in this example. A more interesting, but more limited example 
of an archive library maintenance construction follows: 

lib: lib(filel.o) lib(file2.o) lib(file3.o) 

$(CC) - c $(CFLAGS) $(?:.o=.c) 

ar rv lib $? 

rm $? @ echo lib is now up to date 
.c.a:; 

Here the substitution mode of the macro expansions is used. The 
$? list is defined to be the set of object filenames (inside lib) whose 
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Name 

mkstr - Creates an error message file from C source. 

Syntax 

mkstr [- ] messageflle prefix file ... 

Description 

Mketr is used to create files of error messages. Its use can make pro- 
grams with large numbers of error diagnostics much smaller, and 
reduce system overhead in running the program as the error mes- 
sages do not have to be constantly swapped in and out. 

Mketr will process each specified file, placing a massaged version of 
the input file in a file whose name consists of the specified prefix and 
the original name. The optional dash (- ) causes the error messages 
to be placed at the end of the specified message file for recompiling 
part of a large mkstred program. 

A typical mketr command line is 

mkstr pistrings xx *.c 

This command causes all the error messages from the C source files 
in the current directory to be placed in the file pietringe and processed 
copies of the source for these files to be placed in files whose names 
are prefixed with xx. 

To process the error messages in the source to the message file, 
mketr keys on the string 'errorC' in the input stream. Each time it 
occurs, the C string starting at the "" is placed in the message file 
followed by a null character and a newline character; the null charac- 
ter terminates the message so it can be easily used when retrieved, 
the newline character makes it possible to sensibly cat the error mes- 
sage file to see its contents. The massaged copy of the input file 
then contains a leeek pointer into the file which can be used to 
retrieve the message. For example, the command changes 

error( "Error on reading", a2, a3, a4); 

into 

error(m, a2, a3, a4); 

where m is the seek position of the string in the resulting error mes- 
sage file. The programmer must create a routine error which opens 
the message file, reads the string, and prints it out. The following 
example illustrates such a routine. 
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Name 

nm - Prints name list. 

Syntax 

nm f -gnoOprucv 1 f file ... j 

Description 

nm prints the name list (symbol table) of each object file in the 
argument list. If an argument is an archive, a listing for each 
object file in the archive will be produced. If no file is given, the 
symbols in x.out are listed. 

Each symbol name is preceded by its value in hexadecimal (blanks 
if undefined) and one of the letters U (undefined), A (absolute), T 
(text segment symbol), D (data segment symbol), B (bss segment 
symbol), or C (common symbol), if the symbol is local (non- 
external) the type letter is in lowercase. The output is sorted 
alphabetically. 

Options are: 

-g Print only global (external) symbols. 

— n Sort numerically rather than alphabetically. 

— o Prepend file or archive element name to each output line 
rather than only once. 

— O Print symbol values in octal. 

— p Don't sort; print in symbol— table order. 

— r Sort in reverse order. 

— u Print only undefined symbols. 

— c Print only C program symbols (symbols which begin with 
4 J) as they appeared in the C program. 

—v Also describe the object file and symbol table format. 

Files 

x.out Default input file 

See Also 

ar(CP), ar(F), x.out(F) 
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Name 

prs - Prints an SCCS file. 



PRS{CP) 



Syntax 

pre [- d[dataspec]J [- r(SIDl] [- e] {- I] [- a] files 

Description 

Prt prints, on the standard output, all or part of an SCCS file (see 
eeeefHe(F)) in a user supplied format If a directory is named, prt 
behaves as though each file in the directory were specified as a 
named file, except that nonSCCS files (last component of the path- 
name does not begin with s.), and unreadable files are silently 
ignored. If a name of - is given, the standard input is read; each 
line of the standard input is taken to be the name of an SCCS file or 
directory to be processed; nonSCCS files and unreadable files are 
silently ignored. 

Arguments to pr$, which may appear in any order, consist of 
options, and filenames. 

All the described options apply independently to each named file: 



dj dataepec] 



- t\SID] 



- 1 



Used to specify the output data specification. The 
dataepec is a string consisting of SCCS file data key- 
words (see Data Keywords) interspersed with optional 
user-supplied text. 

Used to specify the 5CCS /identification (SID) string 
of a delta for which information is desired. If no 
SID is specified, the SID of the most recently created 
delta is assumed. 

Requests information for all deltas created earlier 
than and including the delta designated via the - r 
option. 

Requests information for all deltas created later than 
and including the delta designated via the — r 
option. 

Requests printing of information for both removed, 
i.e., delta type = j?, (see rro<fe/(CP)) and existing, 
i.e., delta type = D, deltas. If the - a option is not 
specified, information for existing deltas only is pro- 
vided. 



March 24, 1984 



Page 1 



PRS(CP) 



PRS (CP) 





TABLE 1. SCCS Files Data Keywords 




Keywor&Data Item 


Fie Section 


Value 


Format 


:Dt: 


Delta information 


Delta Table 


See below* 


S 


:DL: 


Delta line statistics 






:Li:/:Ld:/:Lu: 


S 


:Li: 


Lines inserted by Delta 






nnnnn 


s 


:Ld: 


Lines deleted by Delta 






nnnnn 


s 


:Ln: 


Lines unchanged by Delta 






nnnnn 


s 


:DT: 


Delta type 






Dor/? 


s 


:I: 


SCCS ID string (SID) 






:R:.:L:.:B:.:S: 


s 


:R: 


Release number 






nnnn 


s 


:L: 


Level number 






nnnn 


s 


:B: 


Branch number 






nnnn 


s 


:S: 


Sequence number 






nnnn 


s 


:D: 


Date Delta created 






:Dy:/:Dm:/:Dd: 


s 


:Dy: 


Year Delta created 






nn 


s 


:Dm: 


Month Delta created 






nn 


s 


:Dd: 


Day Delta created 






nn 


s 


:T: 


Time Delta created 






:Th:::Tm:::Ts: 


s 


:Th: 


Hour Delta created 






nn 


s 


:Tm: 


Minutes Delta created 






nn 


s 


:Ts: 


Seconds Delta created 






nn 


s 


:P: 


Programmer who created Delta 






logname 


s 


:DS: 


Delta sequence number 






nnnn 


s 


:DP: 


Predecessor Delta seq-no. 






nnnn 


s 


:DI: 


Seq-no. of deltas incl., excl., ignored 






:Dn:/:Dx:/:Dg: 


s 


:Dn: 


Deltas included (seq #) 






:DS::DS:... 


s 


:Dx: 


Deltas excluded (seq #) 






:DS::DS:... 


s 


:Dg: 


Deltas ignored (seq #) 






:DS::DS:... 


s 


:MR: 


MR numbers for delta 






text 


M 


:C: 


Comments for delta 




text 


M 


:UN: 


User names 


User Names 


text 


M 


:FL: 


Flag list 


Flags 


text 


M 


:Y: 


Module type flag 


» 


text 


s 


:MF: 


MR validation flag 


* 


yet or no 


s 


:MP: 


MR validation pgm name 


» 


text 


s 


:KF: 


Keyword error/warning flag 


» 


yet or no 


s 


:BF: 


Branch flag 


» 


yet or no 


s 


:J: 


Joint edit flag 


» 


yet or no 


s 


:LK: 


Locked releases 


» 


:R:... 


s 


:Q: 


User defined keyword 


» 


text 


s 


:M: 


Module name 


» 


text 


s 


:FB: 


Floor boundary 


» 


:R: 


s 


:CB: 


Ceiling boundary 


« 


:R: 


s 


:Ds: 


Default SID 


» 


:I: 


s 


:ND: 


Null delta flag 


» 


yet or no 


s 


:FD: 


File descriptive text 


Comments 


text 


M 


:BD: 


Body 


Body 


text 


M 


:GB: 


Gotten body 


» 


text 


M 


:W: 


A form of what(C) string 


N/A 


:Z::M:\t:I: 


s 


:A: 


A form of what(C) string 


N/A 


Z::Y: :M: :I::Z: 


s 


:Z: 


wkat(C) string delimiter 


N/A 


@(#) 


s 


:F: 


SCCS filename 


N/A 


text 


s 


:PN: 


SCCS file pathname 


Ny 


'A 


text 


s 



♦ :Dt: = :DT: :I: :D: :T: :P: :DS: :DP: 
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Name 

ranlib — Converts archives to random libraries. 

Syntax 

ranlib archive ... 

Description 

Ranlib converts each archive to a form that can be loaded more 
rapidly by the loader, by adding a table of contents named 
_SYMDEF to the beginning of the archive. It uses cr(CP) to 
reconstruct the archive, so sufficient temporary file space must be 
available in the file system containing the current directory. 

See Also 

ld(CP), ar(CP), copy(C), settime(Q 

Notes 

Because generation of a library by or and randomization by ranlib 
are separate, phase errors are possible. The loader 14 warns when 
the modification date of a library is more recent than the creation 
of its dictionary; but this means you get the warning even if you 
only copy the library. On XENIX 68K use of ranlib is optional. 



May 10, 1984 Page 1 



RA TFOR ( CP) RA TFOR { CP) 

Include: 

include filename 

The option - h causes quoted strings to be turned into 27H con- 
structs. - C copies comments to the output, and attempts to format 
it neatly. Normally, continuation lines are marked with an & in 
column 1; the option - 6x makes the continuation character x and 
places it in column 6. 
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Name 

rmdel - Removes a delta from an SCCS file. 

Syntax 

rmdel - rSID files 

Description 

Rmdel removes the delta specified by the SID from each named SCCS 
file. The delta to be removed must be the newest (most recent) 
delta in its branch in the delta chain of each named SCCS file. In 
addition, the SID specified must not be that of aversion being edited 
for the purpose of making a delta. That is, if a p-fUe exists for the 
named SCCS file, the SID specified must not appear in any entry of 
the p-file{ste get{CP)). 

If a directory is named, rmdel behaves as though each file in the 
directory were specified as a named file, except that nonSCCS files 
(last component of the pathname does not begin with s.) and 
unreadable files are silently ignored. If a name of - is given, the 
standard input is read; each line of the standard input is taken to be 
the name of an SCCS file to be processed; nonSCCS files and unread- 
able files are silently ignored. 

Files 

x-file See delta(CP) 

z-file See delta (CP) 

See Also 

delta(CP), get(CP), help(CP), prs(CP), sccsfile(F) 

Diagnostics 

Use Ae/p(CP) for explanations. 
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Name 

sccsdiff - Compares two versions of an SCCS file. 

Syntax 

sccsdiff- rSIDl - rSID2 [- pj [- sn] files 

Description 

Seetdiff compares two versions of an SCCS file and generates the 
differences between the two versions. Any number of SCCS files 
may be specified, but arguments apply to all files. 

- tSID? SID1 and SID2 specify the deltas of an SCCS file that are 

to be compared. Versions are passed to bdijf[C) in the 
order given. 

- p Pipe output for each file through pr(C). 

- sn n is the file segment size that bdiff will pass to diff[C). 

This is useful when diff fails due to a high system load. 

Files 

/tmp/get?? ? ?? Temporary files 

See Also 

bdiff(C), get(CP), help(CP), pr(C) 

Diagnostics 

file: No differenee$ If the two versions are the same. 
Use Ae/p(CP) for explanations. 



March 24, 1984 Page 1 



SPLINE (CP) SPLINE (CP) 

Name 

spline - Interpolates smooth curve. 

Syntax 

spline [ option ] ... 



Description 

Spline takes pairs of numbers from the standard input as abcissas and 
ordinates of a function. It produces a similar set, which is approxi- 
mately equally spaced and includes the input set, on the standard 
output. The cubic spline output has two continuous derivatives, and 
enough points to look smooth when plotted. 

The following options are recognized, each as a separate argument. 

- a Supplies abscissas automatically (they are missing from the 

input); spacing is given by the next argument, or is assumed to 
be 1 if next argument is not a number. 

- k The constant k used in the boundary value computation 

J/o = *J/i , • • - , y« —kyLi 

is set by the next argument. By default k = 0. 

- n Spaces output points so that approximately n intervals occur 

between the lower and upper z limits. (Default n =* 100.) 

- p Makes output periodic, i.e. matches derivatives at ends. First 

and last input values should normally agree. 

- x Next 1 (or 2) arguments are lower (and upper) * limits. Nor- 

mally these limits are calculated from the data. Automatic 
abcissas start at lower limit (default 0). 



Diagnostics 

When data is not strictly monotone in x, epline reproduces the input 
without interpolating extra points. 



Notes 

A limit of 1000 input points is silently enforced. 
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Name 

strip - Removes symbols and relocation bits. 

Syntax 

strip name ... 



Description 

Strip removes the symbol table and relocation bits ordinarily attached 
to the output of the assembler and link editor. This is useful for 
saving space after a program has been debugged. 

The effect of strip is the same as use of the - s option of Id. 

If name is an archive file, ttrip will remove the local symbols from 
any a. out format files it finds in the archive. Certain libraries, such 
as those residing in /lib, have no need for local symbols. By delet- 
ing them, the size of the archive is decreased and link editing perfor- 
mance is increased. 



Files 

/tmp/stm* Temporary file 

See Also 
ld(CP) 
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Name 

tsort - Sorts a file topologically. 

Syntax 

tsort [ file ] 



Description 

T$ort produces on the standard output a totally ordered list of items 
consistent with a partial ordering of items mentioned in the input 
file. If no file is specified, the standard input is understood. 

The input consists of pairs of items (nonempty strings) separated by 
blanks. Pairs of different items indicate ordering. Pairs of identical 
items indicate presence, but not ordering. 



See Also 

lorder(CP) 

Diagnostics 

Odd data: There is an odd number of fields in the input file. 



Notes 



The sort algorithm is quadratic, which can be slow if you have a large 
input list. 
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Name 

val - Validates an SCCS file. 

Syntax 
val - 

val [- s] [- rSID] [- mname] (- ytype] files 

Description 

Val determines if the specified file is an SCCS file meeting the 
characteristics specified by the optional argument list. Arguments to 
val may appear in any order. The arguments consist of options, 
which begin with a - , and named files. 

Val has a special argument, - , which causes reading of the standard 
input until an end-of-file condition is detected. Each line read is 
independently processed as if it were a command line argument list. 

Val generates diagnostic messages on the standard output for each 
command line and file processed and also returns a single 8-bit code 
upon exit as described below. 

The options are defined as follows. The effects of any option apply 
independently to each named file on the command line: 

- s The presence of this argument silences the diagnos- 

tic message normally generated on the standard out- 
put for any error that is detected while processing 
each named file on a given command line. 

- tSID The argument value SID (5CCS /Identification 

String) is an SCCS delta number. A check is made 
to determine if the SID is ambiguous (e. g., rl is 
ambiguous because it physically does not exist but 
implies 1.1, 1.2, etc. which may exist) or invalid (e. 
g., rl.O or rl.1.0 are invalid because neither case 
can exist as a valid delta number). If the SID is 
valid and not ambiguous, a check is made to deter- 
mine if it actually exists. 

- mname The argument value name is compared with the 

SCCS W% keyword in fUe. 

- ytype The argument value type is compared with the SCCS 

%¥% keyword in /He. 
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Name 

xref - Cross-references C programs. 

Syntax 

xref ( file ... ] 

Description 

Xref reads the named file$ or the standard input if no file is specified 
and prints a cross reference consisting of lines of the form 

identifier filename line numbers ... 

Function definition is indicated by a plus sign ( + ) preceding the line 
number. 

See Also 

cref(CP) 
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cc - E name.c |xstr - c - 

cc - c x.c 

mv x.o name.o 

Xttr does not touch the file ttringt unless new items are added, thus 
make can avoid remaking xt.o unless truly necessary. 



Files 

strings Data base of strings 

x.c Massaged C source 

xs.c C source for definition of array "xstr" 

/tmp/xs* Temp file when "xstr name" doesn't touch ttringt 

See Also 

mkstr(CP) 



Credit 



This utility was developed at the University of California at Berkeley 
and is used with permission. 



Notes 



If a string is a suffix of another string in the data base, but the 
shorter string is seen first by xttr , both strings will be placed in the 
data base when just placing the longer one there will do. 
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Diagnostics 

The number of reduce-reduce and shift-reduce conflicts is reported 
on the standard output; a more detailed report is found in the 
y.output file. Similarly, if some rules are not reachable from the 
start symbol, this is also reported. 



Notes 



Because filenames are fixed, at most one yaee process can be active 
in a given directory at a time. 



March 26, 1984 Page 2 



CONTENTS 



System Services (S ) 



intro 

a641,164a 

abort 
abs 
access 
acct 

alarm 

assert 

atof,atoi,atol 

bessel.jO.jl.jn, 

yO.yl.yn 

bsearch 

chdir 

chmod 

chown 

chroot 

chsize 

close 

conv.touppcr, 

tolower.toascii 

creat 

creatsem 

crypt , setkey , encrypt 
ctermid 

ctime.localtime, 

gmtime.asctime, 

tzset 

ctype, isalpha, 

isupper, islower, 

isdigit, isxdigit, 

isalnum, isspace, 

ispunct,isprint, 

isgraph, iscntrl, 

isascii 

curses 

cuserid 

dbm, dbminit, fetch, 

store, delete, 

firstkey,nextkey 



Introduces system services and 
error numbers 

Converts between long integer and 
base 64 ASCII 
Generates anlOT fault 
Returns an integer absolute value 
Determines accessibility of a file 
Enables or disables process 
accounting 

Sets a process* alarm clock 
Helps verify validity of programs 
Converts ASCII to numbers 

Performs Bessel functions 
Performs a binary search 
Changesthe working directory 
Changesmode of a file 
Changesthe owner and group 
of a file 

Changestherootdirectory 
Changesthe size of a file 
Closesa filedescriptor 

Translates characters 
Creates a new file or rewrites an 
existing one 
Creates an instance of a 
binary semaphore 
Performs encryption functions 
Generates a filename for 
a terminal 



Convertsdate and time to ASCII 



Classifies characters 

Performs screen and cursor 

functions 

Reads default entries 



Performs database functions 



1-i 



Btol.ltoB 



Converts between 3 — byte integers and 
long integers 



link 


Links a file to an existing file 


lock 


Locks a process in primary memory 


locking 


Locks a file region for 




reading or writing 


logname 


Finds login name of user 


lsearch 


Performs linear search and update 


lseek 


Moves read/ write file pointer 


malloc,free, 




realloc, calloc 


Allocatesmainmemory 


mknod 


Makes a directory, or a special 




or ordinary file 


mktemp 


Makesaunique filename 


monitor 


Prepares execution profile 


mount 


Mounts a file system 


nap 


Suspends execution fora short 




interval 


nice 


Changes priority of a process 


nlist 


Gets entries from name list 


open 


Opens file for reading or writing 


opensem 


Opens a semaphore 


pause 


Suspendsaprocessuntila signal 




occurs 


perror, sysuerrlist, 




sys_nerr,errno 


Sends system error messages 


pipe 


Creates an interprocess channel 


popen.pclose 


Initiates I/O to or from a process 


printf, fprintf, sprintf Formats output 




profil 


Createsan execution time profile 


ptrace 


Traces a process 


putc,putchar, 




fputc.putw 


Puts a character or word on a 




stream 


putpwent 


Writes a file password entry 


puts.fputs 


Puts a string on a stream 


qsort 


Performs a sort 


rand, srand 


Generatesarandom number 


rdchk 


Checks to see if there is 




datatoberead 


read 


Reads from a file 


regex,regcmp 


Compiles and executes regular 




expressions 


regexp 


Performs regular expression compile 




and match functions 


sbrk 


Changes data segment space 




allocation 


scanf , fscanf , sscanf 


Converts and formats input 


sdenter, sdleave 


Synchronizesaccesstoashared 




data segment 


sdget 


Attaches and detaches a shared 




data segment 



1-iii 





modification times 


wait 


Waits for a child process to 




stop or terminate 


waitsem, nbwaitsem 


Awaits and checks accessto 




a resource goverened by 




a semaphore 


write 


Writes to a file 


xlist.fxlist 


Gets name listentries from files 



1-v 



Index 



Absolute value , integer 
Absolute value , real 
Accounting 


abs 

floor 

acct 


acos function 


trig 


Alannclock 


alarm 


asctime function 


ctime 


asin function 


trig 


atan function 


trig 


atan2 function 


trig 


atoi function 


atof 


atol function 


atof 


Binary search 


bsearch 


brk function 


sbrk 


cabs function 


hypot 


c alloc function 


maSoc 


ceil function 


floor 


Characters, classification 
clearerr function 


ctype 
ferror 


Conversion, 3-byteintegersand longintegers 
Conversion, byte swapping 
Conversion, date and time to ASCII 
Conversion, integerandbase64 ASCII 
Conversion, ASCII to numbers. 
Conversions, output 

Conversions, real to mantissa and exponent 
Conversions, toASCU characters 
cos function 


13tol 

swab 

ctime 

a642 

atof 

ecvt 

frexp 

conv 

trig 


cosh function 


smb. 


Database, functions 
dbminit function 


dbm 
dbm 


Default entries 


defopen 


defread function 


defopen 


delete function 


dbm 


Devices, controls 


focti 


dup2 function 


dup 


encrypt function 


crypt 


Encryption 


crypt 


endgrent function 


getgrent 


endpwent function 


getpwent 


Environment, value 
errno variable 


getenv 
perror 


Error messages 


perror 


Error numbers 


intro 


excel function 


exec 


execle function 


exec 


execlp function 


exec 



fputc function 

fputs function 

free function 

freopen function 

fscanf function 

fstatfunction 

fte 11 function 

ftime function 

fwrite function 

fxlist function 

gcvt function 
getchar function_ 

getegid 

geteuid 

getgid_ 



getgrgid function 

getgrnam function_ 

getpgrp function 

getppid function 

getpwnam function 
getpwuid function_ 

getw function 

gmtime function 

Group, fileentries_ 

gsignal function 

isalnum function 

isalpha function 

isascii function 

isatty function 

iscntrl function 

isdigit function 

isgraph function 

islower function 

isprint function 

ispunct function 

isspace function 

isupper function 

isxdigit function 

jO function 

jl function 

jn function 

164a function 



ldexp function 

Library names 

Library, screen and cursor functions 

Library, standard input and output 

Linear search 

localtime function 



putc 

puts 

malloc 

fopen 

scanf 

~stat 
fseek 
time 
fread 

"xlist 
ecvt 

^getc 
getuid 
getuid 
getuid 
getgrtnt 
getgrent 
getpid 



getpwent 

getpwent 
"gete 

ctime 
"getgrent 

ssignal 
_ctype 

ctype 

crype 

ttyname 
_crype 

crype 
_ctype 
_cfype 
>rype 

ctype 
^pe 

ctype 

ctype 

bessd 

bessd 

bessd 
]a641 

frexp 

intro 

curses 

stdio 

Isearch 

ctime 



putchar function putc 

putw function putc 

Random numbers rand 

realloc function maDoc 

regcmp function regex 

Regularexpressions regex 

rewind function fseek 

Root directory chroot 

sdfree function sdget 

sdleave function sdenter 

sdwaitv function sdgetv 

Semaphore, creation creatsem 

Semaphore, opening opensem 

Semaphore, signaling sigsem 

Semaphore , waiting forresource waitsem 

setgid function setuid 

setgrent function getgrent 

setkey function crypt 

setpwent function getpwent 

Shared data , attaching and detaching sdget 

Shared data, entering and leaving sdenter 

Shared data, sychronized access sdgetv 

Signal, processing signal 

Signal, software ssignal 

sin function trig 

Sorting qsort 

sprintf function .printf 

sqrt function exp 

srand function rand 

sscanf function scanf 

store function dbm 

strcat function string 

strchr function string 

strcmp function string 

strcpy function string 

strcspn function string 

strdup function string 

Stream, buffered input and output fread 

Stream, buffers setbuf 

Stream, character input getc 

Stream, character output putc 

Stream, closing and flushing f close 

Stream, formatted input scanf 

Stream, formatted output printf 

Stream, opening fopen 

Stream, repositioning fseek 

Stream, returning character to ungetc 

Stream, string input gets 



INTRO (S) INTRO (S) 



Name 



intro - Introduces system services, library routines and error 
numbers. 



Syntax 

^include <ermo.h> 



Description 

This section describes all system services. System services include 
all routines or system calls that are available in the operating system 
kernel. These routines are available to a C program automatically as 
part of the standard library libc. Other routines are available in a 
variety of libraries. On 8086/88 and 286 systems, versions for 
Small, Middle, and Large model programs are provided (that is, 
three of each library). 

To use routines in a program that are not part of the standard library 
libc, the appropriate library must be linked. This is done by specify- 
ing - lname to the compiler or linker, where name is the name listed 
below. For example - lm, and - ltermcap are specifications to the 
linker to search the named libraries for routines to be linked to the 
object module. The names of the available libraries are: 

c The standard library containing all system call interfaces, 

Standard I/O routines, and other general purpose services. 

m The standard math library. 

termcap Routines for accessing the termeap data base describing ter- 
minal characteristics. 

curses Screen and cursor manipulation routines. 

dbm Data base management routines. 

Most services that are part of the operating system kernel have one 
or more error returns. An error condition is indicated by an other- 
wise impossible returned value. This is almost always - 1; the indi- 
vidual descriptions specify the details. An error number is also 
made available in the external variable errno. Errno is not cleared 
on successful calls, so it should be tested only after an error has 
been indicated. 

All of the possible error numbers are not listed in each system call 
description because many errors are possible for most of the calls. 
The following is a complete list of the error numbers and their 
names as defined in <error.h>. 
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12 ENOMEM Not enough space 

During an exec, or a&rfc, a program asks for more space than the 
system is able to supply. This is not a temporary condition; the 
maximum space size is a system parameter. The error may also 
occur if the arrangement of text, data, and stack segments 
requires too many segmentation registers, or if there is not 
enough swap space during a/orfc. 

13 EACCES Permission denied 

An attempt was made to access a file in a way forbidden by the 
protection system. 

14 EFAULT Bad address 

The system encountered a hardware fault in attempting to use 
an argument of a system call. 

15 ENOTBLK Block device required 

A nonblock file was mentioned where a block device was 
required, e.g., in mount. 

16 EBUSY Device busy 

An attempt to mount a device that was already mounted or an 
attempt was made to dismount a device on which there is an 
active file (open file, current directory, mounted-on file, active 
text segment). It will also occur if an attempt is made to enable 
accounting when it is already enabled. 

17 EEXIST File exists 

An existing file was mentioned in an inappropriate context, e.g., 
link. 

18 EXDEV Cross-device link 

A link to a file on another device was attempted. 

19 ENODEV No such device 

An attempt was made to apply an inappropriate system call to a 
device; e.g., read a write-only device. 

20 ENOTDIR Not a directory 

A nondirectory was specified where a directory is required, for 
example in a path prefix or as an argument to ehdir(S). 

21 EISDIR Is a directory 

An attempt to write on a directory. 

22 EINVAL Invalid argument 

Some invalid argument (e.g., dismounting a nonmounted dev- 
ice; mentioning an undefined signal in signal, or kill; reading or 
writing a file for which leeek has generated a negative pointer). 
Also set by the math functions described in the (S) entries of 
this manual. 
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between processes vying for control of that region. 

37 ENOTNAM Not a name file 

A createem(S), openeem(S), waiteem(S), or eigtem(S) was issued 
using an invalid semaphore identifier. 

38 ENAVAIL Not available 

An openeem(S) , waitsem(S) or eigeem(S) was issued to a sema- 
phore that has not been initialized by a call to ereateem(S) . A 
eigeem was issued to a semaphore out of sequence; i.e., before 
the process has issued the corresponding waiteem to the sema- 
phore. An nb waiteem was issued to a semaphore guarding a 
resource that is currently in use by another process. The sema- 
phore on which a process was waiting has been left in an incon- 
sistent state when the process controlling the semaphore exits 
without relinquishing control properly; i.e., without issuing a 
waiteem on the semaphore. 

39 EISNAM A name file 

A name file (semaphore, shared data, etc.) was specified when 
not expected. 



Definitions 

Proceee ID 

Each active process in the system is uniquely identified by a positive 
integer called a process ID. The range of this ID is from to 30,000. 

Parent Proceee ID 

A new process is created by a currently active process; see fork(S). 
The parent process ID of a process is the process ID of its creator. 

Proceee Group ID 

Each active process is a member of a process group that is identified 
by a positive integer called the process group ID. This ID is the pro- 
cess ID of the group leader. This grouping permits the signaling of 
related processes; see kill{S). 

Tly Group ID 

Each active process can be a member of a terminal group that is 
identified by a positive integer called the tty group ID. This grouping 
is used to terminate a group of related process upon termination of 
one of the processes in the group; see exit(S) and eignal(S). 
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Pathname and Path Prefix 

A pathname is a null- terminated character string starting with an 
optional slash (/), followed by jsero or more directory names 
separated by slashes, optionally followed by a filename. A filename 
is a string of 1 to 14 characters other than the ASCII slash and null, 
and a directory name is a string of 1 to 14 characters (other than the 
ASCII slash and null) naming a directory. 

If a pathname begins with a slash, the path search begins at the root 
directory. Otherwise, the search begins from the current working 
directory. 

A slash by itself names the root directory. 

Unless specifically stated otherwise, the null pathname is treated as if 
it named a nonexistent file. 



Directory 

Directory entries are called links. By convention, a directory con- 
tains at least two links, . and .., referred to as dot and dot-dot respec- 
tively. Dot refers to the directory itself and dot-dot refers to its 
parent directory. 



Root Directory and Current Working Directory 

Each process has associated with it a concept of a root directory and 
a current working directory for the purpose of resolving pathname 
searches. A process' root directory need not be the root directory of 
the root file system. See ehroot(C) and ehroot(S). 



Fie Acce$$ Permietiont 

Read, write, and execute /search permissions on a file are granted to 
a process if one or more of the following are true: 

The process' effective user ID is super-user. 

The process' effective user ID matches the user ID of the owner 
of the file and the appropriate access bit of the "owner" portion 
(0700) of the file mode is set 

The process' effective user ID does not match the user ID of the 
owner of the file, and the process' group ID matches the group 
of the file and the appropriate access bit of the "group" portion 
(070) of the file mode is set 

The process' effective user ID does not match the user ID of the 
owner of the file, and the process' effective group ID does not 
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Name 

a641, 164a - Converts between long integer and base 64 ASCII. 



Syntax 



long a64l (s) 
char *s; 

char*164a(l) 
long 1; 



Description 

These routines are used to maintain numbers stored in base 64 
ASCII. This is a notation by which long integers can be represented 
by up to six characters; each character represents a "digit" in a radix 
64 notation. 

The characters used to represent "digits" are . for 0, / for 1, 
through for 2 through 11, A through Z for 12 through 37, and a 
through z for 38 through 63. 

A641 takes a pointer to a null-terminated base 64 representation and 
returns a corresponding long value. L64& takes a long argument and 
returns a pointer to the corresponding base 64 representation. 



Notes 



The value returned by 164a is a pointer into a static buffer, the con- 
tents of which are overwritten by each call. 
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Name 

abs - Returns an integer absolute value. 



Syntax 



int abs (i) 
int i; 



Description 

Ab$ returns the absolute value of its integer operand. 

See Also 

fabe in floor(S) 



Notes 



If the largest negative integer supported by the hardware is given, 
the function returns it unchanged. 
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Return Value 

If the requested access is permitted, a value of is returned. Other- 
wise, a value of - 1 is returned and errno is set to indicate the error. 



See Also 

chmod(S), stat(S) 



Notes 



The super-user (root) may access any file, regardless of permission 
settings. 
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Path points to an illegal address. [EFAULT] 

Return Value 

Upon successful completion, a value of is returned. Otherwise, a 
value of - 1 is returned and errno is set to indicate the error. 

See Also 

accton(C), acctcom(C), acct(F) 
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Name 

assert - Helps verify validity of program. 

Syntax 

^include <assert.h> 
assert (expression); 

Description 

This macro is useful for putting diagnostics into programs under 
development When it is executed, if expre$tion is false, it prints 

Assertion failed: file name, line nnn 

on the standard error file and exits. Name is the source filename 
and nnn the source line number of the aeaert statement 



Notes 



To suppress calls to ae$ert, use the option "- DNDEBUG" when 
compiling the program; see ee(CP)). 
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Name 

bessel, jO, jl, jn, yO, yl, yn - Performs Bessel functions. 

Syntax 

^include <math.h> 

double jO(x) 
double x; 

double jl (x) 
double x; 

double jn (n, x); 
double x; 

double yO (x) 
double x; 

double yl (x) 
double x; 

double yn (n, x) 
int n; 
double x; 

Description 

These functions calculate Bessel functions of the first and second 
kinds for real arguments and integer orders. 



Notes 



Negative arguments cause yO, yl, and yn to return a huge negative 
value. 
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Name 

chdir - Changes the working directory. 



Syntax 



int chdir (path) 
char *path; 

Description 

Path points to the pathname of a directory. Chdir causes the named 
directory to become the current working directory, the starting point 
for path searches for pathnames not beginning with /. 

Chdir will fail and the current working directory will be unchanged if 
one or more of the following are true: 

A component of the pathname is not a directory. [ENOTDIR] 

The named directory does not exist [ENOENT] 

Search permission is denied for any component of the path- 
name. (EACCES] 

Path points outside the process' allocated address space. 

[EFAULT] 

Return Value 

Upon successful completion, a value of is returned. Otherwise, a 
value of - 1 is returned and errno is set to indicate the error. 



See Also 

chroot(S) 
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Chmod will fail and the file mode will be unchanged if one or more 
of the following are true: 

A component of the path prefix is not a directory. (ENOTDIR) 

The named file does not exist [ENOENT] 

Search permission is denied on a component of the path prefix. 

[EACCES] 

The effective user ID does not match the owner of the file and 
the effective user ID is not super-user. [EPERM] 

The named file resides on a read-only file system. [EROFS] 

Path points outside the process' allocated address space. 
[EFAULT] 

Return Value 

Upon successful completion, a value of is returned. Otherwise, a 
value of— 1 is returned and errno is set to indicate the error. 

See Also 

chown(S), mknod(S) 
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Name 

chroot - Changes the root directory. 

Syntax 

int chroot (path) 
char *path; 

Description 

Path points to a pathname naming a directory. Chroot causes die 
named directory to become the root directory, the starting point for 
path searches for pathnames beginning with /. 

To change die root directory, the effective user ID of the process 
must be super-user. 

The ".." entry in the root directory is interpreted to mean the root 
directory itself. Thus, ".." cannot be used to access files outside the 
root directory. 

Chroot will fail and the root directory will remain unchanged if one 
or more of the following are true: 

Any component of the pathname is not a directory. [ENOTDIR] 

The named directory does not exist [ENOENTj 

The effective user ID is not super-user. [EPERM] 

Path points outside the process' allocated address space. 
(EFAULT) 

Return Value 

Upon successful completion, a value of is returned. Otherwise, a 
value of - 1 is returned and errno is set to indicate the error. 

See Also 

chdir(S), chroot(C) 
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Name 

close - Closes a file descriptor. 



Syntax 



int close (fildes) 
int fildes ; 



Description 



Fidte is a file descriptor obtained from a creat, open, drip, fenU, or 
pipe system call. CXote closes the file descriptor indicated by fildet. 

dote will fail if fildet is not a valid open file descriptor. [EBADF] 



Return Value 

Upon successful completion, a value of is returned. Otherwise, a 
value of - 1 is returned and errno is set to indicate the error. 



See Also 

creat(S), dup(S), exec(S), fcntl(S), open(S), pipe(S) 
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Notes 



Because Jtoupper and Jtolower are implemented as macros, they 
should not be used where unwanted side effects may occur. Remov- 
ing the JLoupper and _tolov>er macros with the £undef directive 
causes the corresponding library functions to be linked instead. This 
allows any arguments to be used without worry about side effects. 
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The named file resides or would reside on a read-only file sys- 
tem. [EROFS] 

The file is a pure procedure (shared text) file that is being exe- 
cuted. [ETXTBSY] 

The file exists and write permission is denied. [EACCES] 

The named file is an existing directory. [EISDIR] 

Twenty file descriptors are currently open. [EMFILE] 

Path points outside the process' allocated address space. 
[EFAULT] 

Return Value 

Upon successful completion, a nonnegative integer, namely the file 
descriptor, is returned. Otherwise, a value of - 1 is returned and 
errno is set to indicate the error. 

See Also 

close(S), dup(S), Iseek(S), open(S), read(S), umask(S), write(S) 

Notes 

Open(S) is preferred to ereat 
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Diagnostics 

CreaUem returns the value - 1 if an error occurs. If the semaphore 
named by sem_name is already open for use by other processes, 
errno is set to EEXIST. If the rile specified exists but is not a sema- 
phore type, errno is set to ENOTNAM. If the semaphore has not 
been initialized by a call to crcateetn, errno is set to ENAVAIL. 



Notes 



After a creattem you must do a waittem to gain control of a given 
resource. 
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Notes 

The return value from crypt points to static data that is overwritten 
by each call. 
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Name 



ctime, localtime, gmtime, asctime, tzset - Converts date and time 
to ASCII. 



Syntax 



char *ctime (clock) 
long *clock; 

^include <time.h> 

struct tm *localtime (clock) 
long *clock; 

struct tm *gmtime (clock) 
long*clock; 

char *asctime (tm) 
struct tm *tm; 

tzset ( ) 

extern long timezone; 
extern int daylight; 
extern char tzname; 



Description 

Ctime converts a time pointed to by clock (such as returned by 
n'me(S)) into ASCII and returns a pointer to a 2 6- character string in 
the following form: 

Sun Sep 16 01:03:52 lfl73\n\0 

If necessary, fields in this string are padded with spaces to keep the 
string a constant length. 

Localtimc and gmtime return pointers to structures containing the 
time as a variety of individual quantities. These quantities give the 
time on a 24-hour clock, day of month (1-31), month of year (0- 
11), day of week (Sunday ■» 0), year (since 1S00), day of year (0- 
365), and a flag that is nonzero if daylight saving time is in effect. 
Localtime corrects for the time zone and possible daylight savings 
time. Gmtime converts directly to Greenwich time (GMT), which is 
the time the XENIX system uses. 

Atctime converts the times returned by localtime and gmtime to a 
26-character ASCII string and returns a pointer to this string. 
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CTYPE(S) 



Name 



ctype, isalpha, isupper, islower, isdigit, isxdigit, isalnum, isspace, 
ispunct, isprint, isgraph, iscntrl, isascii - Classifies characters. 



Syntax 

^include <ctype.h> 



int is alpha (c) 
int c; 



Description 

These macros classify ASCII-coded integer values by table lookup. 
Each returns nonzero for true, zero for false, Isascii is defined on 
all integer values; the rest are defined only where ieaecii is true and 
on the single non-ASCII value EOF (see stdio(S)). 

it alpha e is a letter 

isupper c is an uppercase letter 

idower e is a lowercase letter 

i$iigit e is a digit [0-9 J 

isxdigit e is a hexidecimal digit [0-9], [A-F] or [a-f] 

isalnum c is an alphanumeric 

itspace e is a space, tab, carriage return, newline, vertical 

tab, or form feed 

itpunet c is a punctuation character (neither control nor 

alphanumeric) 

isprint e is a printing character, octal 40 (space) through 

octal 176 (tilde) 

isgraph e is a printing character, like isprint except false for 

space 

iscntrl e is a delete character (octal 177) or ordinary con- 

trol character (less than octal 40). 

isascii c is an ASCII character, code less than 0200 
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Name 

curses - Performs screen and cursor functions. 

Syntax 

cc [ flags ] files - lcurses - ltermlib [ libraries ] 

Description 

These routines give the user a method of updating screens with rea- 
sonable optimization. They keep an image of the current screen, 
and the user sets up an image of a new one. Then the refre$h() tells 
the routines to make the current screen look like the new one. In 
order to initialize the routines, the routine initeerf) must be called 
before any of the other routines that deal with windows and screens 
are used. 

The routines are linked with the loader option -lcurses. 

See Also 

termcap(F), stty(S), setenv(S) 

Functions 

addch(ch) Adds a character to etdser 

addstr(str) Adds a string to etdter 

box(win,vert,hor) Draws a box around a window 

crmode() Sets cbreak mode 

clear() Clears etdser 

clearok(scr,boolf) Sets clear flag for eer 

clrtobot() Clears to bottom on etdeer 

clrtoeol() Clears to end of line on etdter 

delwin(win) Delete tcin 

echo() Sets echo mode 

eraseQ Erase etdter 

getch() Gets a char through etdeer 

getstr(str) Gets a string through etdter 

gettmode() Gets tty modes 

getyx(win,y,x) Gets (y,x) coordinates 

inch() Gets char at current (y,x) co-ordinates 

initecrQ Initializes screens 

leaveok(win,boolf) Sets leave flag for win 

longname(termbuf,name) Gets long name from termbuf 

move(y,x) Moves to (y,x) on etdeer 

mvcur(lasty,lastx,newy,newx)Actually moves cursor 

newwin(lines,cols,begin_y,begin_x)Creates anew window 
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Name 

cuserid - Gets the login name of the user. 

Syntax 

^include <stdio.h> 

char *cuserid (s) 
char *s; 



Description 

Cueerid returns a pointer to string which represents the login name 
of the owner of the current process. If (int)» is zero, this represen- 
tation is generated in an internal static area, the address of which is 
returned. If (int)# is nonzero, $ is assumed to point to an array of at 
least L_cuserid characters; the representation is left in this array. 
The manifest constant L.cuserid is defined in <stdio.h>. 



Diagnostics 

If the login name cannot be found, cueerid returns NULL; if is 
nonzero in this case, \0 will be placed at *«. 



See Also 

getlogin(S), getpxvent in getpwent(S) 



Notes 



Cueerid uses getpwnam (see getpvent[ S) ) ; thus the results of a user's 
call to the latter will be obliterated by a subsequent call to the 
former. 
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traverse the database: 

for(key«=firstkey(); key.dptr!=NULL; key=nextkey(key)) 

Diagnostics 

All functions that return an int indicate errors with negative values. 
A zero return indicates ok. Routines that return a datum indicate 
errors with a null (0) dptr. 



Notes 



The ".pag" file will contain holes so that its apparent size is about 
four times its actual content. Older XENIX systems may create real 
file blocks for these holes when touched. These files cannot be 
copied by normal means (cp, cat, tp, tar, ar) without rilling in the 
holes. 

Dptr pointers returned by these subroutines point into static storage 
that is changed by subsequent calls. 

The sum of the sizes of a key/content pair must not exceed the 
internal block size (currently 512 bytes). Moreover all key/content 
pairs that hash together must fit on a single block. Store will return 
an error in the event that a disk block fills with inseparable data 

Delete does not physically reclaim file space, although it does make it 
available for reuse. 

The order of keys presented by firttkey and nextkey depends on a 
hashing function. 

These routines are not reentrant, so they should not be used on 
more than one database at a time. 



Credit 



This utility was developed at the University of California at Berkeley 
and is used with permission. 
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Name 

dup, dup2 - Duplicates an open file descriptor. 



Syntax 



int dup (fildes) 
int tildes; 

dup2(fildes, fildes2) 
int fildes, fildes 2; 



Description 

Fide$ is a file descriptor obtained from a ereat, open, dup, fcnti, or 
pipe system call. Dup returns a new file descriptor having the follow- 
ing in common with the original: 

Same open file (or pipe). 

Same file pointer (i.e., both file descriptors share one file 
pointer). 

Same access mode (read, write or read/write). 

The new file descriptor is set to remain open across etee system 
calls. See/cntf(S). 

Dup returns the lowest available file descriptor. DupS causes fildetS 
to refer to the same file as flie$. If filde$2 already referred to an 
open file, it is closed first 

Dup will fail if one or more of the following are true: 

FUde$ is not a valid open file descriptor. [EBADF] 

Twenty file descriptors are currently open. [EMFILEj 

Return Value 

Upon successful completion a nonnegative integer, namely the file 
descriptor, is returned. Otherwise, a value of - 1 is returned and 
trrno is set to indicate the error. 

See Also 

creat(S), close (S), exec(S), fcntl(S), open(S), pipe(S) 
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Name 

excel, execv, execle, execve, exeelp, cxecvp - Executes a file. 



Syntax 



intexeel (path, argO, argl, ..., argn, 0) 
char *path, *argO, *argl, ..., *argn; 

int execv (path, argv) 
char *path, *argv[ ]; 

int execle (path, argO, argl, ..., argn, 0, envp) 
char *path, *argO, *argl, ..., *argn, *envp[ ]; 

int execve (path, argv, envp); 
char *path, *aigv[ ], *envp[ ]; 

int exeelp (file, argO, argl, ..., argn, 0) 
char *file, *argO, *argl, ..., *argn; 

int execvp (file, argv) 
char *file, *argv[ ]; 



Description 

Exec in all its forms transforms the calling process into a new pro- 
cess. The new process is constructed from an ordinary, executable 
file called the "new process file" . There can be no return from a 
successful exec because the calling process is overlaid by the new 
process. 

Path points to a pathname that identifies the new process file. 

File points to the new process file. The path prefix for this file is 
obtained by a search of the directories passed as the environment line 
"PATH =s" (see enwftfn(M)). The environment is supplied by the 
shell (see sh{C)). 

ArgO, argl, ..., argn are pointers to null- terminated character 
strings. These strings constitute the argument list available to the 
new process. By convention, at least argO must be present, and it 
must point to a string that is the same as path (or its last com- 
ponent) . 

Argv is an array of character pointers to null-terminated strings. 
These strings constitute the argument list available to the new pro- 
cess. By convention, argv must have at least one member, and it 
must point to a string that is the same as path (or its last com- 
ponent). Argv is terminated by a null pointer. 
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From C, two interfaces are available. Execl is useful when a known 
file with known arguments is being called; the arguments to execl are 
the character strings constituting the file and the arguments. The 
first argument is conventionally the same as the filename (or its last 
component). A argument must end the argument list 

The execv version is useful when the number of arguments is unk- 
nown in advance. The arguments to ezecv are the name of the file 
to be executed and a vector of strings containing the arguments. 
The last argument string must be followed by a pointer. 

When a C program is executed, it is called as follows: 

main(argc, argv, envp) 

int argc; 

char **argv, **envp; 

where argc is the argument count and argv is an array of character 
pointers to the arguments themselves. As indicated, argc is conven- 
tionally at least one and the first member of the array points to a 
string containing the name of the file. 

Argv is directly usable in another execv because arjt;[ar^c] is 0. 

Envp is a pointer to an array of strings that constitute the environment 
of the process. Each string consists of a name, an "«■", and a null- 
terminated value. The array of pointers is terminated by a null 
pointer. The shell eh(C) passes an environment entry for each glo- 
bal shell variable defined when the program is called. See 
environ[M) for some conventionally used names. The C run-time 
start-off routine places a copy of envp in the global cell environ, 
which is used by execv and execl to pass the environment to any sub- 
programs executed by the current program. The exec routines use 
lower-level routines as follows to pass an environment explicitly: 

execle(file, argO, argl, . . . , argn, 0, environ); 
execve(file, argv, environ); 

Execlp and execvp are called with the same arguments as execl and 
execv, but duplicate the shell's actions in searching for an executable 
file in a list of directories. The directory list is obtained from the 
environment 

Exec will fail and return to the calling process if one or more of the 
following are true: 

One or more components of the new process file's pathname do 
not exist [ENOENT] 

A component of the new process file's path prefix is not a direc- 
tory. [ENOTDIR] 
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Name 

exit - Terminates a process. 



Syntax 



exit (status) 
int status; 



Description 

Exit terminates the calling process. All of the file descriptors open in 
the calling process are closed. 

If the parent process of the calling process is executing a wait, it is 
notified of the calling process' termination and the low-order 8 bits 
(i.e., bits 0377) of ttatue are made available to it; see wat'f(S). 

If the parent process of the calling process is not executing a watt, 
the calling process is transformed into a "zombie process." A zom- 
bie process is a process that only occupies a slot in the process table, 
it has no other space allocated either in user or kernel space. The 
process table slot that it occupies is partially overlaid with time 
accounting information (see <sys/proc.h>) to be used by nme»(S). 

The parent process ID of all of the calling process' existing child 
processes and zombie processes is set to 1. This means the initiali- 
zation process (see tntro(S)) inherits each of these processes. 

An accounting record is written on the accounting file if the system's 
accounting routine is enabled; see aect(S). 

If the process ID, tty group ID, and process group ID of the calling 
process are equal, the SIGHUP signal is sent to each processes that 
has a process group ID equal to that of the calling process. 



See Also 

signal(S), wait(S) 

Warning 

See Warning in eignal(S) 
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Name 

f close, (flush - Closes or flushes a stream. 

Syntax 

^include <stdio.h> 

int fclose (stream) 
FILE *stream; 

int fflush (stream) 
FILE *stream; 



Description 

Fdoee causes any buffers for the named $tream to be emptied, and 
the file to be closed. Buffers allocated by the standard input/output 
system are freed. 

Fcloie is performed automatically upon calling ex#(S). 

Fflueh causes any buffered data for the named output $tream to be 
written to that file. The stream remains open. 

These functions return for success, and EOF if any errors were 
detected. 



See Also 

close(S), fopen(S), setbuf(S) 
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Fentl fails if one or more of the following is true: 

Fidee is not a valid open file descriptor. (EBADFj 

Cmd is FJ5UPFD and 20 file descriptors are currently open. 

[EMFILE] 

Cmd is F_DUPFD and arg is negative or greater than 20. 

[EINVAL] 

Return Value 

Upon successful completion, the value returned depends on entd as 
follows: 

F_DUPFD A new file descriptor 

F.GETFD Value of flag (only the low-order bit is defined) 

F_SETFD Value other than - 1 

FjGETFL Value of file flags 

FJ5ETFL Value other than - 1 

Otherwise, a value of - 1 is returned and errno is set to indicate the 
error. 

See Also 

close (S), exec(S), open(S) 
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Name 

floor, fabs, ceil, fmod - Performs absolute value, floor, ceiling and 
remainder functions. 

Syntax 

f include <math.h> 

double floor (x) 
double x; 

double ceil (x) 
double x; 

double fmod (x, y) 
double x, y; 

double fabs (x) 
double x; 

Description 

Fabe returns \x |. 

Floor returns the largest integer (as a double precision number) not 
greater than x. 

CeH returns the smallest integer not less than x. 

Fmod returns the number / such that x «= iy + /, for some integer t, 
and < f<y. 

See Also 

abs(S) 
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When a file is opened for update, both input and output may be 
done on the resulting stream. However, output may not be directly 
followed by input without an intervening fteek or rewind, and input 
may not be directly followed by output without an intervening feeek, 
rewind, or an input operation which encounters the end of the file. 



See Also 

open(S), fclose(S) 

Diagnostics 

Fopen and freopen return the pointer NULL if filename cannot be 
accessed. 
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process. Otherwise, a value of - 1 is returned to the parent process, 
no child process is created, and errno is set to indicate the error. 

See Also 

exec(S), wait(S) 
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Name 



frexp, ldexp, modf - Splits floating-point number into a mantissa 
and an exponent. 



Syntax 



double frexp (value, eptr) 
double value; 
int *eptr; 

double ldexp (value, exp) 
double value; 

double modf (value, iptr) 
double value, *iptr; 



Description 

Frexp returns the mantissa of a double value as a double quantity, .*, 
of magnitude less than 1, and stores an integer n such that value — 
**2**n indirectly through eptr. 

Ldexp returns the quantity value*(2**exp). 

Modf returns the positive fractional part of value and stores the 
integer part indirectly through iptr. 
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Name 

gamma - Performs log gamma function. 



Syntax 



^include <math.h> 
extern int signgam; 

double gamma (x) 
double x; 



Description 



Gamma returns /nf(|*|)|. The sign of r( \x |) is returned in the 
external integer eigngam. The following C program fragment might 
be used to calculate T: 

y — gamma (x); 
if (y > 88.0) 

error ( ); 
y — exp (y) * signgam; 



Diagnostics 

For negative integer arguments, a huge value is returned, and errno 
is set to EDOM. 
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Name 

getcwd - Gets pathname of current working directory. 



Syntax 



len = getcwd (pnbuf, maxlen); 
int len; 
char *pnbuf; 
int maxlen; 



Description 

Getcwd determines the pathname of the current working directory 
and places it in pnbuf. The length excluding the terminating NULL is 
returned. Maxlen is the length of pnbuf. If the length of the (null- 
terminated) pathname exceeds maxlen, it is treated as an error. 



Diagnostics 

A length <= is returned on error. 



Notes 



maxlen (and pnbuf ) must be 1 more than the true maximum length 
of the pathname. 
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Name 

getgrent, getgrgid, getgrnam, setgrent, endgrent - Get group file 
entry. 

Syntax 

^include <grp.h> 

struct group *getgrent ( ); 

struct group *getgrgid (gitl) 
int gjd; 

struct group *getgmam (name) 
char *name; 

int setgrent ( ) ; 

int endgrent ( ) ; 

Description 

Getgrent, getgrgid and getgrnam each return pointers. The format of 
the structure is defined in /usr/include/grp.h. 

The members of this structure are: 

gr_name The name of the group. 

gr_passwd The encrypted password of the group. 

gr_gid The numerical group ID. 

grjmem Null- terminated vector of pointers to the indivi- 

dual member names. 

Getgrent reads the next line of the file, so successive calls may be 
used to search the entire file. Getgrgid and getgrnam search from the 
beginning of the file until a matching gid or name is found, or end- 
of-file is encountered. 

A call to eetgrent has the effect of rewinding the group file to allow 
repeated searches, Endgrent may be called to close the group file 
when processing is complete. 

Files 

/etc/group 
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Name 

getlogin - Gets login name. 

Syntax 

char *getlogin ( ); 

Description 

Getlogin returns a pointer to the login name as found in /etc/utmp. 
It may be used in conjunction with getpxenam to locate the correct 
password file entry when the same user ID is shared by several login 
names. 

If getlogin is called within a process that is not attached to a terminal 
device, it returns NULL. The correct procedure for determining the 
login name is to call cuterid, or to call getlogin and if it fails, to call 
getpwuid. 

Files 

/etc/utmp 

See Also 

cuserid(S), getgrent(S), getpwent(S), utmp(M) 

Diagnostics 

Returns NULL if name not found. 



Notes 



The return values point to static data whose content is overwritten 
by each call. 
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main (argc, argv) 
int argc; 
char **argv; 

{ 

int c; 

extern int optind; 

extern char *optarg; 

while ((c — getopt (argc, argv, "abf:o:")) !«« EOF) 
switch (c) { 
case 'a': 

if(bflg) 

errflg+ + ; 
else 

aflg+ + ; 
break; 
case V: 

if (aflg) 

errflg+ + ; 
else 

bproc(); 
break; 
case 'f: 

ifile «* optarg; 
break; 
case 'o': 

ofile ■» optarg; 
bufsiza ss 512; 
break; 
case '?': 

errflg+ + ; 

} 
if (errflg) { 

fprintf (stderr, "usage: . . . "); 
exit (S); 

for( ; optind < argc; optind+ + ) { 
if (access (argv [optind], 4)) { 
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Name 

getpid, getpgrp, getppid - Gets process, process group, and parent 
process IDs. 

Syntax 

int getpid ( ) 
int getpgrp ( ) 
int getppid ( ) 

Description 

Getpid returns the process ID of the calling process. 
Getpgrp returns the process group ID of the calling process. 
Getppid returns the parent process ID of the calling process. 

See Also 

exec(S), fork(S), intro(S), setpgrp(S), signal(S) 
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Name 

getpwent, getpwuid, getpwnam, setpwent, endpwent - Gets pass- 
word file entry. 

Syntax 

^include <pwd.h> 

struct passwd *getpwent ( ); 

struct passwd *getpwuid (uid) 
int uid; 

struct passwd 'getpwnam (name) 
char *name; 

int setpwent ( ); 

int endpwent ( ) ; 



Description 

Getpwent, getpwuid and getpwnam each returns a pointer to a struc- 
ture containing the fields of an entry line in the password file. The 
structure of a password entry is defined in /usr/include/pwd.h. 

The fields have meanings described in patswd(M). (The 
pw_comment field is unused.) 

Getpwent reads the next line in the file, so successive calls can be 
used to search the entire file. Getpwuid and getpwnam search from 
the beginning of the file until a matching uid or name is found, or 
EOF is encountered. 

A call to tetpwent has the effect of rewinding the password file to 
allow repeated searches. Endpwent may be called to close the pass- 
word file when processing is complete. 



Files 

/etc/passwd 

See Also 

getlogin(S), getgrent(S), passwd(M) 
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Name 

gets, fgets - Gets a string from a stream. 

Syntax 

^include <stdio.h> 

char*gets (s) 
char *s; 

char *fgets (s, n, stream) 

char *s; 

int n; 

FILE 'stream; 

Description 

Gete reads a string into e from the standard input stream stdin. The 
function replaces the newline character at the end of the string with 
a null character before copying to •. Gete returns a pointer to «. 

Fgete reads characters from the stream until a newline character is 
encountered or until n- 1 characters have been read. The characters 
are then copied to the string «. A null character is automatically 
appended to the end of the string before copying. Fgets returns a 
pointer to s. 

See Also 

ferror(S), fopen(S), fread(S), getc(S), puts(S), scanf(S) 

Diagnostics 

GeU and fgets return the constant pointer NULL upon end-of-file or 
error. 

Notes 

Gets deletes the newline ending its input, but fgets keeps it. 
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Name 

hypot, cabs - Determines Euclidean distance. 

Syntax 

^include <math.h> 

double hypot (x, y) 
double x, y; 

double cabs (z) 
struct {double x, y;} z; 

Description 

Hypot and eabe return 

sqrt(x*x + y*y) 
Both take precautions against unwarranted overflows. 

See Also 

$qrt in exp(S) 
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Name 

kill - Sends a signal to a process or a group of processes. 



Syntax 



int kill (pid, sig) 
int pid, sig; 



Description 

Kill sends a signal to a process or a group of processes. The process 
or group of processes to which the signal is to be sent is specified by 
pid. The signal that is to be sent is specified by tig and is either one 
from the list given in tignal(S), or 0. If tig is (the null signal), 
error checking is performed but no signal is actually sent. This can 
be used to check the validity of pid. 

The effective user ID of the sending process must match the 
effective user ID of the receiving process unless, the effective user ID 
of the sending process is super-user, or the process is sending to 
itself. 

The processes with a process ID of and a process ID of 1 are special 
processes (see tntro(S)) and will be referred to below as procO and 
prod respectively. 

If pid is greater than zero, tig will be sent to the process whose pro- 
cess ID is equal to pid. Pid may equal 1. 

If pid is 0, tig will be sent to all processes excluding procO and prod 
whose process group ID is equal to the process group ID of the 
sender. 

If pid is - 1 and the effective user ID of the sender is not super-user, 
tig will be sent to all processes excluding proeO and prod whose real 
user ID is equal to the effective user ID of the sender. 

If pid is - 1 and the effective user ID of the sender is super-user, tig 
will be sent to all processes excluding proeO and prod. 

If pid is negative but not - 1, tig will be sent to all processes whose 
process group ID is equal to the absolute value of pid. 

Kill will fail and no signal will be sent if one or more of the follow- 
ing are true: 

Sig is not a valid signal number. [EINVAL] 

No process can be found corresponding to that specified by pid. 
[ESRCHl 
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Name 

13tol, lto!3 - Converts between 3-byte integers and long integers. 



Syntax 



13tol (lp, cp, n) 
long *lp; 
char *cp; 
int n; 

ltol3 (cp, lp, n) 
char *cp; 
long *lp; 
int n; 



Description 



LStol converts a list of n 3-byte integers packed into a character 
string pointed to by cp into a list of long integers pointed to by lp. 

LtolS performs the reverse conversion from long integers (lp) to 3- 
byte integers (ep). 

These functions are useful for file system maintenance where the 
block numbers are 3 bytes long. 



See Also 

filesystem(F) 
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Return Value 

Upon successful completion, a value of is returned. Otherwise, a 
value of - 1 is returned and errno is set to indicate the error. 

See Also 

ln(C) 
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Name 

locking - Locks or unlocks a file region for reading or writing. 



Syntax 



lockingffildes, mode, size); 
int fildes, mode; 
long size; 



Description 

Locking allows a specified number of bytes in a file to be controlled 
by the locking process. Other processes which attempt to read or 
write a portion of the file containing the locked region may sleep 
until the area becomes unlocked depending upon the mode in which 
the file region was locked. A process that attempts to write to or 
read a file region that has been locked against reading and writing by 
another process (using the LK_LOCK or LK_NBLCK mode) will sleep 
until the region of the file has been released by the locking process. 
A process that attempts to write to a file region that has been locked 
against writing by another process (using the LK_RLCK or 
LK_NBRLCK mode) will sleep until the region of the file has been 
released by the locking process, but a read request for that file region 
will proceed normally. 

A process that attempts to lock a region of a file that contains areas 
that have been locked by other processes will sleep if it has specified 
the LK_LOCK or LK_RLCK mode in its lock request, but will return with 
the error EACCES if it specified LK_NBLCK or LK.NBRLCK. 

FUde$ is the value returned from a successful creat, open, drip, or pipe 
system call. 

Mode specifies the type of lock operation to be performed on the file 
region. The available values for mode are: 



LK.UNLCK 

Unlocks the specified region. The calling process releases a 
region of the file it had previously locked. 

LK.LOCK 1 

Locks the specified region. The calling process will sleep until 
the entire region is available if any part of it has been locked by 
a different process. The region is then locked for the calling 
process and no other process may read or write in any part of 
the locked region, (lock against read and write). 



March 24, 1984 Page 1 



L OCKING ( S) L OCKING ( S ) 

If a process has done more than one open on a file, all locks put on 
the file by that process will be released on the first close of the file. 

Although no error is returned if locks are applied to special files or 
pipes, read/write operations on these types of files will ignore the 
locks. Locks may not be applied to a directory. 

See Also 

creat(S), open(S), read(S), write(S), dup(S), close(S), lseek(S) 

Diagnostics 

Locking returns the value (int) -1 if an error occurs. If any portion 
of the region has been locked by another process for the LKJLOCK 
and LK.RLCK actions and the lock request is to test only, errno is set 
to EACCES. If the file specified is a directory, errno is set to 
EACCES. If locking the region would cause a deadlock, errno is set 
to EDEADLOCK. If there are no more free internal locks, errno is set 
to EDEADLOCK. 
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Name 

lsearch - Performs linear search and update. 



Syntax 



char *lsearch (key, base, nelp, width, compar) 

char *key; 

char *base; 

int *nelp; 

int width; 

int (*compar)(); 



Description 



Lttarch is a linear search routine generalized from Knuth (6.1) 
Algorithm Q. It returns a pointer into a table indicating the location 
at which a datum may be found. If the item does not occur, it is 
added at the end of the table. The first argument is a pointer to the 
datum to be located in the table. The second argument is a pointer 
to the base of the table. The third argument is the address of an 
integer containing the number of items in the table. It is incre- 
mented if the item is added to the table. The fourth argument is the 
width of an element in bytes. The last argument is the name of the 
comparison routine. It is called with two arguments which are 
pointers to the elements being compared. The routine must return 
zero if the items are equal, and nonzero otherwise. 



Notes 



Unpredictable events can occur if there is not enough room in the 
table to add a new item. 



See Also 

bsearch(S), qsort(S) 
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See Also 

creat(S), dup(S), fcntl(S), open(S) 



March 24, 1984 Page 2 



A/ALLOC (S) MALLOC{S) 

object. 

Diagnostics 

Malloe, re alloc and calloc return a null pointer (0) if there is no 
available memory or if the area has been detectably corrupted by 
storing outside the bounds of a block. When re alloc returns 0, the 
block pointed to by ptr may be destroyed. 
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shared memory file or a semaphore. 

Mknod may be invoked only by the super-user for file types other 
than named pipe special. 

Mknod will fail and the new file will not be created if one or more of 
the following are true: 

The process' effective user ID is not super-user. [EPERM] 

A component of the path prefix is not a directory. [ENOTDIR] 

A component of the path prefix does not exist. [ENOENT] 

The directory in which the file is to be created is located on a 
read-only file system. [EROFS] 

The named file exists. (EEX1ST] 

Path points outside the process 1 allocated address space. 

[EFAULT] 



Return Value 

Upon successful completion a value of is returned. Otherwise, a 
value of - 1 is returned and errno is set to indicate the error. 



See Also 

mkdir(C), mknod(C), chmod(S), creatsem(S), exec(S), sdget(S), 
umask(S), filesystem(F) 



Notes 

Semaphore files should be created with the ereat$em(S) system call. 
Share data files should be created with the edget(S) system call. 
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Name 

monitor - Prepares execution profile. 



Syntax 



monitor (lowpc, highpc, buffer, bufsize, nfunc) 
int(*lowpc)( ),(*highpc)( ); 
short buffer[ ]; 
int bufsize, nfunc; 



Description 

Monitor is an interface to profil(S). Lowpc and highpc are the 
addresses of two functions; buffer is the address of a user-supplied 
array of bufeize short integers. Monitor arranges to record a histo- 
gram of periodically sampled values of the program counter, and of 
counts of calls of certain functions, in the buffer. The lowest 
address sampled is that of lowpc and the highest is just below highpc. 
At most nfunc call counts can be kept; only calls of functions com- 
piled with the profiling option - p of cc(CP) are recorded. For the 
results to be significant, especially where there are small, heavily 
used routines, it is suggested that the buffer be no more than a few 
times smaller than the range of locations sampled. 

To profile the entire program, it is sufficient to use 

extern etext(); 

monitor(2, etext, buf, bufsize, nfunc); 

Etext lies just above all the program text. 

To stop execution monitoring and write the results on the file 
mon.out, use 

monitor(O); 

prof (CP) can then be used to examine the results. 

Files 

mon.out 

See Also 

cc(CP), prof(CP), profil(S) 
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Name 

mount- Mounts a file system. 



Syntax 



int mount (spec, dir, rwflag) 
char *spec, *dir; 
int rwflag; 



Description 

Mount requests that a removable file system contained on the block 
special file identified by epee be mounted on the directory identified 
by dir. Spec and dir are pointers to pathnames. 

Upon successful completion, references to the file dir will refer to 
the root directory on the mounted file system. 

The low-order bit of rwflag is used to control write permission on 
the mounted file system; if 1, writing is forbidden, otherwise writing 
is permitted according to individual file accessibility. 

Mount may be invoked only by the super-user. 

Mount will fail if one or more of the following are true: 

The effective user ID is not super-user. [EPERM] 

Any of the named files does not exist. [ENOENT] 

A component of a path prefix is not a directory. [ENOTDIR] 

Spec is not a block special device. [ENOTBLK] 

The device associated with tptc does not exist. [ENXIO] 

Dir is not a directory. [ENOTDIR] 

Spec or dir points outside the process' allocated address space. 
[EFAULT] 

Dir is currently mounted on, is someone's current working 
directory or is otherwise busy. [EBUSY] 

The device associated with epec is currently mounted. [EBUSY] 
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Name 

nap - Suspends execution for a short interval. 



Syntax 



long nap( period) 
long period; 



Description 



The current process is suspended from execution for at least the 
number of milliseconds specified by period, or until a signal is 
received. 



Return Value 

On successful completion, a long integer indicating the number of 
milliseconds actually slept is returned. If the process recieved a signal 
while napping, the return value will be -1, and errno will be set to 
EINTR. 



Notes 



This function is driven by the system clock, which in most cases has 
a granularity of tens of milliseconds. 



See Also 

sleep(S) 
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Name 

nlist - Gets entries from name list. 



Syntax 



^include <a.out.h> 
nlist (filename, nl) 
char *filename; 
struct nlist nl[ ]; 



Description 

Nliet examines the name list in the given executable output file and 
selectively extracts a list of values. The name list consists of an 
array of structures containing names, types and values. The list is 
terminated with a null name. Each name is looked up in the name 
list of the file. If the name is found, the type and value of the name 
are inserted in the next two fields. If the name is not found, both 
entries are set to 0. See a.otrf(F) for a discussion of the symbol 
table structure. 



See Also 

a.out(F), xlist(S) 

Diagnostics 

Nliet return - 1 and sets all type entries to if the file cannot be 
read, is not an object file, or contains an invalid name list. Other- 
wise, nliet returns 0. A return value of does not indicate that any 
or all symbols were found. 



March 24, 1984 Page 



OPEN(S) 



O^PPEND 



O CREAT 



O TRUNC 



OEXCL 



O.SYNCW 



OPEN(S) 

If OJ^DELAY is clear: 

The open will block until carrier is present 

If set, the file pointer will be set to the end of the file 
prior to each write. 

If the file exists, this flag has no effect. Otherwise, 
the file's owner ID is set to the process' effective user 
ID, the file's group ID is set to the process' effective 
group ID, and the low-order 12 bits of the file mode 
are set to the value of mode modified as follows (see 
creat(S)): 

All bits set in the process' file mode creation 
mask are cleared. See uma«fc(S). 

The "save text image after execution bit" of the 
mode is cleared. See ehmod(S). 

If the file exists, its length is truncated to and the 
mode and owner are unchanged. 

If O.EXCL and OjCREAT are set, open will fail if the 
file exists. 

Every write to this file descriptor will be synchro- 
nous, that is, when the write system call completes 
data is guaranteed to have been written to disk. 



Upon successful completion a nonnegative integer, the file descrip- 
tor, is returned. 

The file pointer used to mark the current position within the file is 
set to the beginning of the file. 

The new file descriptor is set to remain open across exec system 
calls. See fcntl(S). 

No process may have more than 20 file descriptors open simultane- 
ously. 

The named file is opened unless one or more of the following are 
true: 

A component of the path prefix is not a directory. (ENOTDIR) 

0_CREAT is not set and the named file does not exist. 

[ENOENT] 

A component of the path prefix denies search permission. 
[EACCES] 
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Name 

opensem - Opens a semaphore. 



Syntax 



sem_num = opensem(sem_name); 
int sem_num; 
char *sem_name; 



Description 



Openeem opens a semaphore named by «m_nome and returns the 
unique semaphore identification number eemjnvm used by waiteem 
and eigeem. Createem should always be called to initialize the sema- 
phore before the first attempt to open it, or to reset the semaphore if 
it has become inconsistent due to an exiting process neglecting to do 
a sigsem after issuing a waitsem. 



See Also 

creatsem(S), waitsem(S), sigsem (S) 



Diagnostics 



Openeem returns the value - 1 if an error occurs. If the semaphore 
named does not exist, errno is set to ENOENT. If the file specified is 
not a semaphore file (i.e., a file previously created by a process using 
a call to createem), errno is set to ENOTNAM. If the semaphore has 
become invalid due to inappropriate use, errno is set to ENOTAVA.IL. 
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Name 

perror, sy&jerrlist, sys_nerr, errno — Sends system error messages. 

Syntax 

perror (s) 
char *s; 

int sys_nerr; 
char *sysuerrllst( ]; 

int errno; 

Description 

Perror produces a short error message on the standard error, 
describing the last error encountered during a system call from a C 
program. First the argument string s is printed, then a colon, then 
the message and a newline. To be of most use, the argument 
string should be the name of the program that incurred the error. 
The error number is taken from the external variable errno, which 
is set when errors occur but not cleared when correct calls are 
made. 

To simplify variant formatting of messages, the vector of message 
strings sysjerrlist is provided; errno can be used as an index in this 
table to get the message string without the newline. Sys-nerr is the 
number of entries provided for in the table; it should be checked 
because new error codes may be added to the system before they 
are added to the table. 

See Also 

intro(S) 
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Name 

popen, pclose - Initiates I/O to or from a process. 

.Syntax 

^include <stdio.h> 

FILE *popen (command, type) 
char 'command, *type; 

int pclose (stream) 
FILE *stream; 



Description 

The arguments to popen are pointers to null- terminated strings con- 
taining, respectively, a shell command line and an I/O mode, either 
"r" for reading or "w" for writing. Popen creates a pipe between 
the calling process and the command to be executed. The value 
returned is a stream pointer that can be used (as appropriate) to 
write to the standard input of the command or read from its stan- 
dard output. 

A stream opened by popen should be closed by pclott, which waits 
for the associated process to terminate and returns the exit status of 
the command. Because open files are shared between processes, a 
type "r" command may be used as an input filter, and a type "w" 
as an output filter. 



See Also 

pipe(S), wait(S), fclose(S), fopen(S), system(S) 

Diagnostics 

Popen returns a null pointer if files or processes cannot be created, 
or if the shell cannot be accessed. 

Pcloee returns - 1 if etream is not associated with a popen ed com- 
mand. 



Notes 

Only one stream opened by popen can be in use at once. Buffered 
reading before opening an input filter may leave the standard input 
of that filter mispositioned. Similar problems with an output filter 
may be forestalled by careful buffer flushing; see fetoee{S). 
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maximum number of significant digits for the g conversion, or 
the maximum number of characters to be printed from a string 
in s conversion. The precision takes the form of a period (.) 
followed by a decimal digit string: a null digit string is treated as 
zero. 

An optional 1 specifying that a following d, o, u, x, or X conver- 
sion character applies to a long integer arg. 

A character that indicates the type of conversion to be applied. 

A field width or precision may be indicated by an asterisk (*) instead 
of a digit string. In this case, an integer arg supplies the field width 
or precision. The arg that is actually converted is not fetched until 
the conversion letter is seen, so the args specifying field width or 
precision must appear before the arg (if any) to be converted. 

The flag characters and their meanings are: 

- The result of the conversion will be left- justified within 

the field. 

+ The result of a signed conversion will always begin with a 

sign (+ or- ). 

blank If the first character of a signed conversion is not a sign, 

a blank will be prepended to the result. This implies that 
if the blank and + flags both appear, the blank flag will 
be ignored. 

# This flag specifies that the value is to be converted to an 

"alternate form." For c, d, s, and u conversions, the flag 
has no effect. For o conversion, it increases the precision 
to force the first digit of the result to be a zero. For x 
(X) conversion, a nonzero result will have Ox (OX) 
prepended to it. Fqr e, E, f, g, and G conversions, the 
result will always contain a decimal point, even if no 
digits follow the point (normally, a decimal point appears 
in the result of these conversions only if a-digit follows 
it). For g and G conversions, trailing zeroes will not be 
removed from the result (which they normally are). 

The conversion characters and their meanings are: 

d,o,u,x,X The integer arg is converted to signed decimal, unsigned 
octal, decimal, or hexadecimal notation (x and X), 
respectively; the letters abcdcf are used for x conversion 
and the letters ABCDEF for X conversion. The precision 
specifies the minimum number of digits to appear; if the 
value being converted can be represented in fewer digits, 
it will be expanded with leading zeroes. The default pre- 
cision is 1. The result of converting a zero value with a 
precision of zero is a null string (unless the conversion is 
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Examples 

To print a date and time in the form "Sunday, July 3, 10:02", where 
weekday and month are pointers to null-terminated strings: 

printf("%5, %s %i, %.2d:%.2d", weekday, month, day, hour, 
min); 

To print n to five decimal places: 

printf("pi ■= %.5F, 4*atan(1.0)); 



See Also 

ecvt(S), putc(S), scanf(S) 
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Name 

ptrace - Traces a process. 



Syntax 



int ptrace (request, pid, addr, data); 
int request, pid, data; 



Description 

Ptrace provides a means by which a parent process may control the 
execution of a child process. Its primary use is in the implementa- 
tion of breakpoint debugging; see aib(CP). The child process 
behaves normally until it encounters a signal (see tignal(S) for the 
list), at which time it enters a stopped state and its parent is notified 
via wct<(S). When the child is in the stopped state, its parent can 
examine and modify its "memory image" using ptrace. Also, the 
parent can cause the child either to terminate or continue, with the 
possibility of ignoring the signal that caused it to stop. 

The addr argument is dependant on the underlying machine type, 
specifically the process memory model. On systems where the 
memory management mechanism provides a uniform and linear 
address space to user processes, the argument is declared as: 

int *addr; 

which is sufficient to address any location in the process' memory. 
On machines where the user address space is segmented (even if the 
particular program being traced has only one segment allocated), the 
form of the addr argument is: 

struct { 

int offset; 

int segment; 
} *addr; 

which allows the caller to specify segment and offset in the process 
address space. 

The request argument determines the precise action to be taken by 
ptrace and is one of the following: 

This request must be issued by the child process if it 
is to be traced by its parent. It turns on the child's 
trace flag that stipulates that the child should be left in 
a stopped state upon receipt of a signal rather than the 
state specified by June; see eignal(S). The pid, addr, 
and data arguments are ignored, and a return value is 
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7 This request causes the child to resume execution. If 
the data argument is 0, all pending signals including 
the one that caused the child to stop are canceled 
before it resumes execution. If the data argument is a 
valid signal number, the child resumes execution as if 
it had incurred that signal and any other pending sig- 
nals are canceled. In a linear address space memory 
model, the value of addr must be (int *)1, or in a seg- 
mented address space the segment part of addr must 
be zero and the offset part of addr must be (int *)1. 
Upon successful completion, the value of data is 
returned to the parent. This request will fail if data is 
not or a valid signal number, in which case a value 
of - 1 is returned to the parent process and the 
parent's errno is set to EIO. 

8 This request causes the child to terminate with the 
same consequences as e«tfc(S). 

9 Execution continues as in request 7; however, as soon 
as possible after execution of at least one instruction, 
execution stops again. The signal number from the 
stop is SIGTRAP. This is part of the mechanism for 
implementing breakpoints. The exact implementation 
and behaviour is somewhat CPU dependant. 

As indicated, these calls (except for request 0) can be used 
only when the subject process has stopped. The watt system 
call is used to determine when a process stops; in such a 
case the termination status returned by wait has the value 
0177 to indicate stoppage rather than genuine termination. 

To prevent security violations, ptraee inhibits the set-user-id 
facility on subsequent exee{S) calls. If a traced process calls 
exec, it will stop before executing the first instruction of the 
new image showing signal SIGTRAP. 



Errors 

Ptraee will in general fail if one or more of the following are true: 

Request is an illegal number. [EIO] 

Pid identifies a child that does not exist or has not executed a 
ptraee with request 0. [ESRCH] 

Notes 

The implementation and precise behaviour of this system call is 
inherently tied to the specific CPU and process memory model in 
use on a particular machine. Code using this call is likely to not be 
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Name 

putc, putchar, fputc, putw - Puts a character or word on a stream. 

Syntax 

^include <stdio.h> 

int putc (c, stream) 

chare; 

FILE *stream; 

putchar (c) 

int fputc (c, stream) 
FILE *stream; 

int putw (w, stream) 

int w; 

FILE 'stream; 



Description 

Putc appends the character c to the named output etream. It returns 
the character written. 

Putehar[e) is defined as ptifc(c,stdout ). 

Fputc behaves like putc, but is a genuine function rather than a 
macro; it may therefore be used as an argument. Fputc runs more 
slowly than putc, but takes less space per invocation. 

Putw appends the word (i.e., integer) w to the output ttrtam. Putw 
neither assumes nor causes special alignment in the file. 

The standard stream stdout is normally buffered if and only if the 
output does not refer to a terminal; this default may be changed by 
eetbuf(S). The standard stream stderr is by default unbuffered 
unconditionally, but use of freopen (see /opcn(S)) will cause it to 
become unbuffered; eetbuf, again, will set the state to whatever is 
desired. When an output stream is unbuffered information appears 
on the destination file or terminal as soon as written; when it is 
buffered many characters are saved up and written as a block. See 
fflueh is fcloee(S). 



See Also 

fclose(S), ferror(S), fopen(S), fread(S), getc(S), printf(S), pute(S) 
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Name 

putpwent - Writes a password file entry. 

Syntax 

# include <pwd.h> 

int putpwent (p, f) 
struct passwd *p; 
FlLE*f; 

Description 

Putpwent is the inverse of getpwent( S) . Given a pointer to a paeewd 
structure created by getpwent (or getpwuid or getpwnam), putpwent 
writes a line on the stream /. The line matches the format of 
/etc/passwd 



See Also 

passwd(M), getpwent(S) 



Diagnostics 

Putpwent returns nonzero if an error was detected during its opera- 
tion, otherwise zero. 
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Name 

qsort - Performs a sort. 



Syntax 



qsort (base, nel, width, compar) 
char *base; 
int nel, width; 
int (*compar)( ); 



Description 



Qeort is an implementation of the quicker-sort algorithm. The first 
argument is a pointer to the base of the data; the second is the 
number of elements; the third is the width of an element in bytes; 
the last is the name of the comparison routine. It is called with two 
arguments which are pointers to the elements being compared. The 
routine must return an integer less than, equal to, or greater than 
according to how much the first argument is to be considered less 
than, equal to, or greater than the second. 



See Also 

sort(C), bsearch(S), lsearch(S), string(S) 
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Name 

rdchk - Checks to see if there is data to be read. 



Syntax 



rdchk (fdes); 
int fdes; 



Description 

Rdchk checks to see if a process will block if it attempts to read the 
file designated by fdee. Rdchk returns 1 if there is data to be read or 
if it is the end of the file (EOF). In this context, the proper 
sequence of calls using rdchk is: 

if(rdchk(fildes) > 0) 

read(fildes, buffer, nbytes); 



See Also 

read(S) 

Diagnostics 

Rdchk returns -1 if an error occurs (e.g., EBADF), if the process 
will block if it issues a read and 1 if it is okay to read. EBADF is 
returned if a rdchk is done on a semaphore file or if the file specified 
doesn't exist. 
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Read will fail if one or more of the following are true: 

Fdde$ is not a valid file descriptor open for reading. [EBADF] 
Buf points outside the allocated address space. [EFAULTj 

Return Value 

Upon successful completion a nonnegative integer is returned indi- 
cating the number of bytes actually read. Otherwise, a - 1 is 
returned and errno is set to indicate the error. 

See Also 

creat(S), dup(S), fcntl(S), ioctl(S), open(S), pipe(S), tty(M) 



Notes 



Reading a region of a file locked with locking causes read to hang 
indefinitely until the locked region is unlocked. 
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to be applied, {m,} is analogous to {m, infinity}. The plus 
( + ) and star (*) operations are equivalent to {1,} and {0,} 
respectively. 

( . . . )$n The value of the enclosed regular expression is to be 
returned. The value will be stored in the (n+/)th argu- 
ment following the subject argument. At present, at most 
ten enclosed regular expressions are allowed. Regex makes 
its assignments unconditionally. 

(...) Parentheses are used for grouping. An operator, e.g. *, 
+ , {}, can work on a single character or a regular expres- 
sion enclosed in parenthesis. For example, (a*(cb+ )*)$0. 

By necessity, all the above defined symbols are special. They must, 
therefore, be escaped to be used as themselves. 



Examples 

Example 1: 

char *cursor, *newcursor, *ptr; 

newcursor = regex((ptr=regcmp(' , '\n'',0)), cursor); 
free(ptr); 

This example will match a leading newline in the subject string 
pointed at by cursor. 

Example 2: 

char ret0[9|; 

char *newcursor, *name; 

name = regcmpC([A- Za- z][A- za- zO- 9_]{0,7})$0",0); 
newcursor = regex(name,"123Testing321",retO); 

This example will match through the string "Testing3" and will 
return the address of the character after the last matched character 
(cursor+ 11). The string "Testing3" will be copied to the character 
array retO. 

Example 8: 

#include "file.i" 

char 'string, *newcursor; 

newcursor = regex(name, string); 

This example applies a precompiled regular expression in file.i (see 
regcmp( CP)) against string. 
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Name 

regexp - Performs regular expression compile and match functions. 

' Syntax 

^define INIT <declarations> 

#define GETC( ) <getc code> 

^define PEEKC( ) <peekc code> 

^define UNGETC(c) <ungetc code> 

#define RETURN( pointer) <return code> 

^define ERROR(val) <error code> 

# include <regexp.h> 

char *compile(instring, expbuf, endbuf, eof) 
char *instring, *expbuf, *endbuf; 

int step( string, expbuf) 
char *string, *expbuf; 

Description 

This entry describes general purpose regular expression matching 
routines in the form of ed(C), defined in /usr/include/regexp.h. 
Programs such as ed(C), eed[C) t grep{C), 6«(C), e*pr(C), etc., 
which perform regular expression matching use this source file. In 
this way, only this file need be changed to maintain regular expres- 
sion compatibility. 

The interface to this file is unpleasantly complex. Programs that 
include this file must have the following five macros declared before 
the "#include <regexp.h>" statement. These macros are used by 
the compile routine. 

GETC( ) Returns the value of the next character in the 

regular expression pattern. Successive calls to 
GETC( ) should return successive characters of 
the regular expression. 

PEEKC( ) Returns the next character in the regular 

expression. Successive calls to PEEKC( ) 
should return the same character (which 
should also be the next character returned by 
GETC()). 
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The parameter eof is the character which marks the end of the regu- 
lar expression. For example, in cd(C), this character is usually a /. 

Each programs that includes this file must have a #define statement 
for INIT. This definition will be placed right after the declaration for 
the function compile and the opening curly brace ({). It is used for 
dependent declarations and initializations. It is most often used to 
set a register variable to point the beginning of the regular expres- 
sion so that this register variable can be used in the declarations for 
GETC(), PEEKC() and UNGETC(). Otherwise it can be used to 
declare external variables that might be used by GETC( ), PEEKC( ) 
and UNGETC(). See the example below of the declarations taken 
from grep(C). 

There are other functions in this file which perform actual regular 
expression matching, one of which is the function step. The call to 
$tep is as follows: 

step(string, expbuf) 

The first parameter to step is a pointer to a string of characters to be 
checked for a match. This string should be null terminated. 

The second parameter expbuf is the compiled regular expression 
which was obtained by a call of the function compile. 

The function step returns one, if the given string matches the regular 
expression, and zero if the expressions do not match. If there is a 
match, two external character pointers are set as a side effect to the 
call to etep. The variable set in ttep is loci. This is a pointer to the 
first character that matched the regular expression. The variable 
loc2, which is set by the function advance, points the character after 
the last character that matches the regular expression. Thus if the 
regular expression matches the entire line, loci will point to the first 
character of string and loeS will point to the null at the end of tiring. 

Step uses the external variable circf which is set by compile if the reg- 
ular expression begins with *. If this is set then etep will only try to 
match the regular expression to the beginning of the string. If more 
than one regular expression is to be compiled before the the first is 
executed the value of circf should be saved for each compiled 
expression and circf should be set to that saved value before each 
call to step. 

The function advance is called from ttep with the same arguments as 
ttep. The purpose of ttep is to step through the ttring argument and 
call advance until advance returns a one indicating a match or until 
the end of ttring is reached. If one wants to constrain ttring to the 
beginning of the line in all cases, ttep need not be called, simply call 
advance. 

When advance encounters a * or \{ \} sequence in the regular 
expression it will advance its pointer to the string to be matched as 
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Name 

sbrk, brk - Changes data segment space allocation. 



Syntax 



char *sbrk (incr) 
int incr; 



Description 

Sbrk is used to dynamically change the amount of space allocated for 
the calling process' data segment; see eiec(S). The change is made 
by resetting the process' break value. The break value is the address 
of the first location beyond the end of the data segment. The 
amount of allocated space increases as the break value increases. 

Sbrk adds titer bytes to the break value and changes the allocated 
space accordingly. Incr can be negative, in which case the amount of 
allocated space is decreased. 

Sbrk will fail without making any change in the allocated space if 
such a change would result in more space being allocated than is 
allowed by a system- imposed maximum (see u/tmtf(S)). [ENOMEMj 



Return Value 

Upon successful completion, $brk and brk return pointers to the 
beginning of the allocated space. Otherwise, a value of - 1 is 
returned and errno is set to indicate the error. 



See Also 

exec(S) 
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% A single %is expected in the input at this point; no assignment 
is done. 

d A decimal integer is expected; the corresponding argument 
should be an integer pointer. 

o An octal integer is expected; the corresponding argument should 
be an integer pointer. 

x A hexadecimal integer is expected; the corresponding argument 
should be an integer pointer. 

s A character string is expected; the corresponding argument 
should be a character pointer pointing to an array of characters 
large enough to accept the string and a terminating \0, which 
will be added automatically. The input field is terminated by a 
space character or a newline. 

c A character is expected; the corresponding argument should be 
a character pointer. The normal skip over space characters is 
suppressed in this case; to read the next nonspace character, use 
9«ls. If a field width is given, the corresponding argument 
should refer to a character array; the indicated number of char- 
acters is read. 

e,f A floating-point number is expected; the next field is converted 
accordingly and stored through the corresponding argument, 
which should be a pointer to a float. The input format for 
floating-point numbers is an optionally signed string of digits, 
possibly containing a decimal point, followed by an optional 
exponent field consisting of an E or an e, followed by an option- 
ally signed integer. 

[ Indicates a string that is not to be delimited by space characters. 
The left bracket is followed by a set of characters and a right 
bracket; the characters between the brackets define a set of char- 
acters making up the string. If the first character is not a caret 
( *), the input field consists of all characters up to the first char- 
acter that is not in the set between the brackets; if the first char- 
acter after the left bracket is a *, the input field consists of all 
characters up to the first character that is in the set of the 
remaining characters between the brackets. The corresponding 
argument must point to a character array. 

The conversion characters d, o, and x may be capitalized and/or pre- 
ceded by 1 to indicate that a pointer to long rather than to int is in 
the argument list. Similarly, the conversion characters e and f may 
be capitalized and/or preceded by 1 to indicate that a pointer to dou- 
ble rather than to float is in the argument list. The character h will, 
some time in the future, indicate short data items. 

Sean/ conversion terminates at EOF, at the end of the control string, 
or when an input character conflicts with the control string, In the 
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Name 

sdenter, sdleave - Synchronizes access to a shared data segment. 

Syntax 

#includc <sd.h> 

int sdenter(addr,flags) 
char *addr; 
int flags; 

int sdleave<addr) 
char *addr; 

Description 

Sdenter is used to indicate that the current process is about to 
access the contents of a shared data segment. The actions per- 
formed depend on the value of flags. Flags values are formed by 
OR-ing together entries from the following list: 

SD-NOWA1T if another process has called sdenter but not 
sdleave for the indicated segment, and the seg- 
ment was not created with the SD.UNLOCK flag 
set, return an error instead of waiting for the 
segment to become free. 

SD.WRlTE Indicates that the process intends to modify the 

data, if SD.WRlTE isn't specified changes made 
to data are not guarenteed to be reflected in other 
proceses. 

Sdleave is used to indicate that the current process is done modi- 
fying the contents of a shared data segment. 

Only changes made between invocatations of sdenter and sdleave 
are guaranteed to be reflected in other processes. Sdenter and 
sdleave are very fast; consequently, it is recommended that they be 
called frequently rather than leave sdenter in effect for any period 
of time, in particular, system calls should be avoided between 
sdenter and sdleave calls. 

The fork system call is forbidden between calls to sdenter and 
sdleave if the segment was created without the SD.UNLOCK flag. 
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Name 

sdget- Attachs and detachs a shared data segment. 

Syntax 

^include <sd.h> 

char *sdget(path, flags, [size, mode]) 
char*path; 
int flags, mode; 
long size; 

int sdfree(addr); 
char *addr; 



Description 

Sdget attachs a shared data segment to the data space of the current 
process. The actions performed are controlled by the value of flagt. 
Rage values are constructed by OR-ing flags from the following list: 

SDJIDONLY 

Attach the segment for reading only. 

SD_WRITE Attach the segment for both reading and writing. 

SD_CREAT If the segment named by path exists, this flag has no 
effect. Otherwise, the segment is created according to 
the values of eize and mode. Read and write access to 
the segment is granted to other processes based on the 
permissions passed, in mode, and functions the same as 
those for regular files. Execute permission is meaning- 
less. The segment is initialized to contain all zeroes. 

SD.UNLOCK 

If the segment is created because of this call, the seg- 
ment will be made so that more than one process can 
be between sdenter and sdleave calls. 

Sdfree detachs the current process from the shared data segment that 
is attached at the specified address. If the current process has done 
an ede titer but not a tdleave for the specified segment, an edleave will 
be done before detaching the segment. 

When no process remains attached to the segment, the contents of 
that segment disappear, and no process can attach to the segment 
without creating it by using the SD_CREAT flag in edget. 
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Name 

sdgetv, sdwaitv - Synchronizes shared data access. 

Syntax 

^include <sd.h> 

int sdgetv(addr) 

int sdwaitv(addr, vnum) 

char *addr; 

int vnum; 



Description 

Sdgetv and tdwaitv may be used to synchronize cooperating processes 
that are using shared data segments. The return value of both rou- 
tines is the version number of the shared data segment attached to 
the process at address addr. The version number of a segment 
changes whenever some process does an edleave for that segment 

Sdgetv simply returns the version number of the indicated segment 

Sdwaitv forces the current process to sleep until the version number 
for the indicated segment is no longer equal to vnum. 



Return Value 

Upon successful completion, both edgetv and tdwaitv return a positive 
integer that is the current version number for the indicated shared 
data segment Otherwise, a value of -1 is returned, and errno is set 
to indicate the error. 



See Also 

sdenter(S), sdget(S) 
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Name 

setjmp, longjmp - Performs a nonlocal "goto". 

Syntax 

^include <setjmp.h> 

int setjmp (env) 
jmp_buf env; 

int longjmp (env, val) 
jmp_bufenv; 



Description 

These routines are useful for dealing with errors and interrupts 
encountered in a low-level subroutine of a program. 

Setjmp saves its stack environment in env for later use by longjmp. It 
returns value 0. 

Longjmp restores the environment saved by the last call of tetjmp. It 
then returns in such a way that execution continues as if the call of 
tetjmp had just returned the value val to the corresponding call to 
$etjmp. The routine which calls tetjmp must not itself have returned 
in the interim. Longjmp cannot return the value 0. If longjmp is 
invoked with a second argument of 0, it will return 1. All accessible 
data have values as of the time longjmp was called. The only excep- 
tion to this are register variables. The value of register variables are 
undefined in the routine that called tetjmp when the corresponding 
longjmp is invoked. 



See Also 

signal(S) 
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Name 

setuid, setgid - Sets user and group IDs. 



Syntax 



int setuid ( uid) 
int uid; 

int setgid (gid) 
int gid; 



Description 

Setuid is used to set the real user ID and effective user ID of the cal- 
ling process. 

Setgid is used to set the real group ID and effective group ID of the 
calling process. 

If the effective user ID of the calling process is super-user, the real 
user (group) ID and effective user (group) ID are set to uid {gid). 

If the effective user ID of the calling process is not super-user, but 
its real user (group) ID is equal to uid {gid), the effective user 
(group) ID is set to uid {gid). 

Setuid will fail if the real user (group) ID of the calling process is not 
equal to uid {gid) and its effective user ID is not super-user. 

[EPERM] 



Return Value 

Upon successful completion, a value of is returned. Otherwise, a 
value of - 1 is returned and errno is set to indicate the error. 



See Also 

getuid(S), intro(S) 
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Name 

signal - Specifies -what to do upon receipt of a signal. 

Syntax 

£ in elude < signal. h> 

int ('signal (sig, func))( ) 

int sig; 

int (*func)( ); 



Description 

Signal allows the calling process to choose one of three ways in 
which it is possible to handle the receipt of a specific signal. Sig 
specifies the signal and fune specifies the choice. 

Sig can be assigned any one of the following except SIGKILL: 

Hangup 

Interrupt 

Quit 

Illegal instruction (not reset when caught) 

Trace trap (not reset when caught) 

I/O trap instruction 

Emulator trap instruction 

Floating-point exception 

Kill (cannot be caught or ignored) 

Bus error 

Segmentation violation 

Bad argument to system call 

Write on a pipe with no one to read it 

Alarm clock 

Software termination signal 

User-defined signal 1 

User-defined signal 2 

Death of a child (see Warning below) 

Power fail (see Warning below) 

See below for the significance of the asterisk in the above list. 

Fune is assigned one of three values: SIGJDFL, SIGJGN, or a func- 
tion addreee. The actions prescribed by these values of are described 
below. 

The SIGJDFL value causes termination of the process upon receipt 
of a signal. Upon receipt of the signal rig, the receiving process is to 
be terminated with the following consequences: 
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SIGBUP 


01 


SI G3 NT 


02 


SIGQUIT 


03* 


SI GILL 


04* 


SIGTRAP 


05* 


SI GOT 


06* 


SIGEMT 


07* 


SIGFPE 


08* 


SIGKILL 


09 


SIGBUS 


10* 


SIGSEGV 


11* 


SIGSYS 


12* 


SIGPIPE 


13 


SIGALRM 


14 


SIGTERM 


15 


SIGUSRl 


16 


SIGUSR2 


17 


SIGCLD 


18 


SIGPWR 


19 
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2. When a signal that is to be caught occurs during a read, a write, 
an open, or an ioeti system call on a slow device (like a termi- 
nal; but not a file), during a pause system call, or during a watt 
system call that does not return immediately due to the 
existence of a previously stopped or zombie process, the signal 
catching function will be executed and then the interrupted sys- 
tem call will return a - 1 to the calling process with errno set to 
EINTR. 

3. Note that the signal SIGKILL cannot be caught. 

A call to signal cancels a pending signal tig except for a pending SIG- 
KILL signal. 

Signal will fail if one or more of the following are true: 

Sig is an illegal signal number, including SIGKILL. [EINVAL] 

Fune points to an illegal address. [EFAULT] 

Return Value 

Upon successful completion, signal returns the previous value of 
fune for the specified signal sig. Otherwise, a value of - 1 is 
returned and errno is set to indicate the error. 

See Also 

kill(C), kill(S), pause(S), ptrace(S), wait(S), setjmp(S). 

Warning 

Two other signals that behave differently than the signals described 
above exist in this release of the system; they are: 

SIGCLD 18 Death of a child (not reset when caught) 

SIGPWR 19 Power fail (not reset when caught) 

There is no guarantee that, in future releases of XENIX, these signals 
will continue to behave as described below; they are included only 
for compatibility with other versions of XENIX. Their use in new 
programs is strongly discouraged. 

For these signals, June is assigned one of three values: SIG_DFL, 
SIG_IGN, or a function address. The actions prescribed by these 
values of are as follows: 

SIGJDFL - ignore signal 

The signal is to be ignored. 
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Name 

sigsem - Signals a process waiting on a semaphore. 



Syntax 



sigsem(sem_num) ; 
int sem_num; 



Description 

Sigeem signals a process that is waiting on the semaphore tem_num 
that it may proceed and use the resource governed by the sema- 
phore. Sigeem is used in conjunction with viaiteem(S) to allow syn- 
chronization of processes wishing to access a resource. One or more 
processes may waiteem on the given semaphore and will be put to 
sleep until the process which currently has access to the resource 
issues a fig tern call. If there are any waiting processes, tig t em causes 
the process which is next in line on the semaphore's queue to be 
rescheduled for execution. The semaphore's queue is organized in 
first in first out (FIFO) order. 



See Also 

creatsem(S), opensem(S), waitsem(S) 

Diagnostics 

Sigeem returns the value (int) -1 if an error occurs. If temjnum does 
not refer to a semaphore type file, errno is set to ENOTNAM. If 
eem_num has not been previously opened by opentem, errno is set to 
EBADF. If the process issuing a sigsem call is not the current 
"owner" of the semaphore (i.e., if the process has not issued a 
waiteem call before the sigsem), errno is set to ENAVAIL. 
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Name 

sleep - Suspends execution for an interval. 



Syntax 



unsigned sleep (seconds) 
unsigned seconds; 



Description 

The current process is suspended from execution for the number of 
eeeonde specified by the argument The actual suspension time may 
be less than that requested for because scheduled wakeups occur at 
fixed 1-second intervals, and any caught signal will terminate the 
$leep following execution of that signal's catching routine. Also, the 
suspension time may be longer than requested by an arbitrary 
amount due to the scheduling of other activity in the system. The 
value returned by deep will be the "unslept" amount (the requested 
time minus the time actually slept) in case the caller had an alarm 
set to go off earlier than the end of the requested deep time, or 
premature arousal due to another caught signal. 

The routine is implemented by setting an alarm signal and pausing 
until it (or some other signal) occurs. The previous state of the 
alarm signal is saved and restored. The calling program may have 
set up an alarm signal before calling $leep; if the deep time exceeds 
the time till such alarm signal, the process sleeps only until the 
alarm signal would have occurred, and the caller's alarm catch rou- 
tine is executed just before the eleep routine returns, but if the deep 
time is less than the time till such alarm, the prior alarm time is 
reset to go off at the same time it would have gone off without the 
intervening tleep. 



See Also 

alarm(S), nap(S), pause(S), signal(S) 
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Notes 



There are some additional signals with numbers outside the range 1 
through 15 that are used by the standard C library to indicate error 
conditions. Thus, some signal numbers outside the range 1 through 
15 are legal, although their use may interfere with the operation of 
the standard C library. 
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st_atime Time when file data was last accessed. Changed by the 
following system calls: creat(S), mknod(S), pipe(S), 
vtime(S), and read(S). 

st_mtime Time when data was last modified. Changed by the fol- 
lowing system calls: ereat(S), mknod(S), ptpe(S), 
ufimc(S), and tonte(S). 

st_ctime Time when file status was last changed. Changed by the 
following system calls: chmod(S), chown(S), creat(S), 
link(S), mknod(S), pi'pc(S), un"me(S), and tcniCe(S). 

st_rdev Device indentification. In the case of block and character 
special files this contains the device major and minor 
numbers; in the case of shared memory and semaphores, 
it contains the type code. The file 

/usr/include/sys /types. h contains the macros ma/orQ 
and minor{) for extracting major and minor numbers 
from $t_rdev. See /usr/include/sys/stat.h for the sema- 
phore and shared memory type code values SJNSEM and 
SJNSHD. 

Stat will fail if one or more of the following are true: 

A component of the path prefix is not a directory. [ENOTDIR] 

The named file does not exist. [ENOENT] 

Search permission is denied for a component of the path prefix. 

[EACCES] 

Buf or path points to an invalid address. (EFAULT] 
Fstat will fail if one or more of the following are true: 
Fides is not a valid open file descriptor. [EBADF] 
Buf points to an invalid address. [EFAULT] 

Return Value 

Upon successful completion a value of is returned. Otherwise, a 
value of - 1 is returned and errno is set to indicate the error. 

See Also 

chmod(S), chown(S), creat(S), link(S), mknod(S), time(S), 
unlink(S) 
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See Also 

open(S), close(S), read(S), write(S), ctermid(S), cuserid(S), 
fclose(S), ferror(S), fopen(S), fread(S), fseek(S), getc(S), gets(S), 
popen(S), printf(S), putc(S), puts(S), scanf(S), setbuf(S), 
system(S), tmpnam(S) 



Diagnostics 

Invalid stream pointers can cause grave disorder, possibly including 
program termination. Individual function descriptions describe the 
possible error conditions. 
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Name 

string, strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen, strchr, 
strrchr, strpbrk, strspn, strcspn, strtok, strdup - Perform string 
operations. 

Syntax 

char *strcat (si, s2) 
char *sl, *s2; 

char *strncat (si, s2, n) 
char *sl, *s2; 
int n; 

int strcmp (si, s2) 
char *sl, *s2; 

int strncmp (si, s2, n) 
char *sl, *s2; 
int n; 

char *strcpy (si, s2) 
char *sl, *s2; 

char *strncpy (si, s2, n) 
char *sl, *s2; 
int n; 

int strlen (s) 
char *s; 

char *strchr (s, c) 
char *s, c; 

char *strrchr(s, c) 
char *s, c; 

char *8trpbrk (si, s2) 
char *sl, *s2; 

int strspn (si, s2) 
char *sl, *s2; 

int strcspn (si, s2) 
char *sl, *s2; 

char *strtok (si, s2) 
char *sl, *s2; 

char*strdup(s) 
char *s; 
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Notes 

Stremp uses native character comparison, which is signed on some 
machines, unsigned on others. 

All string movement is performed character by character starting at 
the left. Thus overlapping moves toward the left will work as 
expected, but overlapping moves to the right may yield surprises. 
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Name 

sync - Updates the super-block. 

Syntax 

sync ( ) 

Description 

Syne causes all information in memory that should be on disk to be 
written out. This includes modified super-blocks, modified inodes, 
and delayed block I/O. 

It should be used by programs which examine a file system, for 
example ftek{C), df(C), etc. 

The writing, although scheduled, is not necessarily complete upon 
return from $yne. 

See Also 

sync(C) 
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Name 



tgetent, tgetnum, tgetflag, tgetstr, tgoto, tputs - Performs terminal 
functions. 



Syntax 



char PC; 
char *BC; 
char *UP; 
short os peed; 

tgetent(bp, name) 
char *bp, *name; 

tgetnum(id) 
char *id; 

tgetflagfid) 
char *id; 

char *tgetstr (id, area) 
char *id, **area; 

char *tgoto (cm, destcol, destline) 
char *cm; 

tputs (cp, affcnt, outc) 
register char *cp; 
int affcnt; 
int (*outc)(); 



Description 

These functions extract and use capabilities from the terminal capa- 
bility data base termeap{M). These are low level routines; see 
eur$ee[S) for a higher level package. 

Tgetent extracts the entry for terminal name into the buffer at bp. Bp 
should be a character buffer of size 1024 and must be retained 
through all subsequent calls to tgetnum, tgetflag, and tgetetr. Tgetent 
returns - 1 if it cannot open the termcap file, if the terminal name 
given does not have an entry, and 1 if all goes well. It will look in 
the environment for a TERMCAP variable. If found, and the value 
does not begin with a slash, and the terminal type name is the same 
as the environment string TERM, the TERMCAP string is used 
instead of reading the termcap file. If it does begin with a slash, the 
string is used as a pathname rather than /etc/termeap. This can speed 
up entry into programs that call tgetent, as well as to help debug new 
terminal descriptions or to make one for your terminal if you can't 
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Name 

time, ftime -Gets time and : date. 

Syntax 

time_t time ((long *) 0) 

time_t time (tloc) 
tirne_t *tloc; 

^include <sys /types. h> 
^include <sys/timeb.h> 

ftime(tp) 
struct timeb *tp; 



Description 

Time returns the current system time in seconds since 00:00:00 
GMT, January 1, 1970. 

If tloc (taken as an integer) is nonzero, the return value is also 
stored in the location to which Uoe points. 

Ftime returns the time in a structure (see below under Return 
Value.) 

Time will fail if the points to an illegal address. [EFAULT] Likewise, 
ftime will fail if tp points to an illegal address. [EFAULT] 



Return Value 

Upon successful completion, time returns the value of time. Other- 
wise, a value of - 1 is returned and emtio is set to indicate the error. 

The ftime entry fills in a structure pointed to by its argument, as 
defined by <sys/timeb.h>: 

/• 

* Structure returned by ftime system call 

•/ 

struct timeb { 

time_t time; 
unsigned short millitm; 
short timezone; 
short dstflag; 

}; 
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Name 

times - Gets process and child process times. 

Syntax 

^include < times. h> 

long times (buffer) 
struct tmbuf { 

long utime; 

long stime; 

long cu time; 

long cs time; 
} buffer; 

Description 

Times fills the structure pointed to by buffer with time-accounting 
information. This information comes from the calling process and 
each of its terminated child processes for which it has executed a 
wait( S) . 

All times are in clock ticks where a tick is some fraction of a second 
defined in mocAinc(M). 

Utime is the CPU time used while executing instructions in the user 
space of the calling process. 

Stime is the CPU time used by the system on behalf of the calling 
process. 

Cutime is the sum of the utimes and eutimes of the child processes. 

Cetime is the sum of the etimes and eetimes of the child processes. 

Timet will fail if buffer points to an illegal address. [EFAULT] 

Return Value 

Upon successful completion, time* returns the elapsed real time, in 
clock ticks, since an arbitrary point in the past, such as the system 
start-up time. This point does not change from one invocation of 
timet to another. If timet fails, a - 1 is returned and errno is set to 
indicate the error. 

See Also 

exec(S), fork(S), time(S), wait(S), machine(M) 
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Name 

tmpnam - Creates a name for a temporary file. 

Syntax 

#include <stdio.h> 

char *tmpnam (s) 
char *s; 



Description 

Tmpnam generates a filename that can safely be used for a tem- 
porary file. If (int)« is zero, tmpnam leaves its result in an internal 
static area and returns a pointer to that area. The next call to 
tmpnam will destroy the contents of the area. If (int)« is nonzero, « 
is assumed to be the address of an array of at least L_tmpnam 
bytes; tmpnam places its result in that array and returns as its 
value. 

Tmpnam generates a different filename each time it is called. 

Files created using tmpnam and either fopen or ereat are only tem- 
porary in the sense that they reside in a directory intended for tem- 
porary use, and their names are unique. It is the user's responsibil- 
ity to use «n/infc(S) to remove the file when its use is ended. 



See Also 

creat(S), unlink(S), fopen(S), mktemp(S) 



Notes 



If called more than 17,576 times in a single process, tmpnam will 
start recycling previously used names. 

Between the time a filename is created and the file is opened, it is 
possible for some other process to create a file with the same name. 
This can never happen if that other process is using tmpnam or 
mktemp, and the filenames are chosen so as to render duplication by 
other means unlikely. 
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Name 

ttyname, isatty - Finds the name of a terminal. 

Syntax 

char *ttyname (Hides) 
int isatty (fildes) 

Description 

Ttyname returns a pointer to the null- terminated pathname of the 
terminal device associated with file descriptor fildes. 

Isatty returns 1 if fildes is associated with a terminal device, other- 
wise. 

Files 

/dev/* 

Diagnostics 

Ttyname returns a null pointer (0) if fildes does not describe a termi- 
nal device in directory /dev. 



Notes 



The return value points to static data whose content is overwritten 
by each call. 
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Name 

umask - Sets and gets file creation mask. 



Syntax 



int umask (cmask) 
int cmask; 



Description 



Umaek sets the process' file mode creation mask to emaek and 
returns the previous value of the mask. Only the low-order 9 bits of 
emaek and the file mode creation mask are used. 



Return Value 

The previous value of the file mode creation mask is returned. 

See Also 

mkdir(C), mknod(C), sh(C), chmod(S), mknod(S), open(S) 
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Name 

uname - Gets name of current XENIX system. 

Syntax 

#include <sys/utsname.h> 

int uname (name) 
struct utsname *name; 



Description 

Uname stores information identifying the current XENIX system in 
the structure pointed to by name. 

Uname uses the structure defined in <sys/utsname.h>: 

struct utsname { 

char sysname[9]; 
char nodename[9|; 
char release[9]; 
char version[9]; 
unsigned short sysorigin; 
unsigned short sysoem; 
long sysserial; 

}; 

Uname returns a null- terminated character string naming the current 
XENIX system in the character array sysname. Similarly, nodename 
contains the name that the system is known by on a communications 
network. Release and version further identify the operating system. 
Sysorigin and eyseom identify the source of the XENIX version. Sys- 
serial is a software serial number which may be zero if unused. 

Uname will fail if name points to an invalid address. [EFAULT] 



Return Value 

Upon successful completion, a nonnegative value is returned. Oth- 
erwise, - 1 is returned and errno is set to indicate the error. 
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Name 

ungetc - Pushes character back into input stream. 

Syntax 

^include <stdio.h> 

int ungetc (c, stream) 

chare; 

FILE *stream; 



Description 

Ungetc pushes the character c back on an input stream. The charac- 
ter will be returned by the next getc call on that stream. Ungetc 
returns c. 

One character of pushback is guaranteed provided something has 
been read from the stream and the stream is actually buffered. 
Attempts to push EOF are rejected. 

Feeek{S) erases all memory of pushed back characters. 



See Also 

fseek(S), getc(S), setbuf(S) 

Diagnostics 

Ungetc returns EOF if it can't push a character back. 
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Return Value 

Upon successful completion, a value of is returned. Otherwise, a 
value of - 1 is returned and errno is set to indicate the error. 

See Also 

rm(C), close(S), link(S), open(S) 
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Name 

utime - Sets file access and modification times. 



Syntax 



^include <sys /types. h> 
int utime (path, times) 
char *path; 
struct utimbuf *times; 



Description 

Path points to a pathname naming a file. Utime sets the access and 
modification times of the named file. 

If timet is NULL, the access and modification times of the file are set 
to the current time. A process must be the owner of the file or have 
write permission to use utime in this manner. 

If times is not NULL, timet is interpreted as a pointer to a utimbuf 
structure and the access and modification times are set to the values 
contained in the designated structure. Only the owner of the file or 
the super-user may use utime this way. 

The times in the following structure are measured in seconds since 
00:00:00 GMT, Jan. 1, 1970. 

struct utimbuf { 

time_t actime; /* access time */ 

time_t modtime; /* modification time */ 

>; 

Utime will fail if one or more of the following are true: 
The named file does not exist [ENOENT] 
A component of the path prefix is not a directory. [ENOTDIRj 

Search permission is denied by a component of the path prefix. 

[EACCES] 

The effective user ID is not super-user and not the owner of the 
file and timet is not NULL. [EPERM] 

The effective user ID is not super-user and not the owner of the 
file and timet is NULL and write access is denied. [EACCES] 

The file system containing the file is mounted read-only. 

[EROFS] 
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Name 

wait - Waits for a child process to stop or terminate. 



Syntax 



int wait (stat_loc) 
int *stat_loc; 

int wait ((int *)0) 



Description 

Wait suspends the calling process until it receives a signal that is to 
be caught (see «0naJ(S)), or until any one of the calling process' 
child processes stops in a trace mode (see ptrace(S)) or terminates. 
If a child process stopped or terminated prior to the call on wait, 
return is immediate. 

If etatjloc (taken as an integer) is nonzero, 16 bits of information 
called "status" are stored in the low-order 16 bits of the location 
pointed to by etatjloc. Statue can be used to differentiate between 
stopped and terminated child processes and if the child process ter- 
minated, status identifies the cause of termination and passes useful 
information to the parent. This is accomplished in the following 
manner: 

If the child process stopped, the high-order 8 bits of status will 
be zero and the low-order 8 bits will be set equal to 0177. 

If the child process terminated due to an exit call, the low-order 
8 bits of status will be zero and the high-order 8 bits will contain 
the low-order 8 bits of the argument that the child process 
passed to exit; see extif(S). 

If the child process terminated due to a signal, the high-order 8 
bits of status will be zero and the low-order 8 bits will contain 
the number of the signal that caused the termination. In addi- 
tion, if the low-order seventh bit (i.e., bit 200) is set, a "core 
image" will have been produced; see eignal(S). 

If a parent process terminates without waiting for its child processes 
to terminate, the parent process ID of each child process is set to 1. 
This means the initialization process inherits the child processes; see 
tntro(S), 
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Name 



waiteem, nbwaitsem - Awaits and checks access to a resource 
governed by a semaphore. 



Syntax 



waitsem( sem_num) ; 
int sem_num; 

nbwaitaem(sem_num); 
int sem_num; 



Description 

Waiteem gives the calling process access to the resource governed by 
the semaphore eemjnum. If the resource is in use by another pro- 
cess, wait8em will put the process to sleep until the resource becomes 
available; nbwaitsem will return the error ENAVAIL. Waiteem and 
nbwaiteem are used in conjunction with eigeem to allow synchroniza- 
tion of processes wishing to access a resource. One or more 
processes may waiteem on the given semaphore and will be put to 
sleep until the process which currently has access to the resource 
issues eigeem. Sigeem causes the process which is next in line on the 
semaphore's queue to be rescheduled for execution. The 
semaphore's queue is organized in first in first out (FIFO) order. 



See Also 

creatsem(S), opensem(S), sigsem(S) 

Diagnostics 

Waiteem returns the value (int) -1 if an error occurs. If eemjnum 
has not been previously opened by a call to openeem or createem, 
ermo is set to EBADF. If eem_num does not refer to a semaphore 
type file, errno is set to ENOTNAM. All processes waiting (or 
attempting to wait) on the semaphore when the process controlling 
the semaphore exits without relinquishing control (thereby leaving 
the resource in an undeterminate state) return with errno set to ENA- 
VAIL. 
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below). 

If the file being written is a pipe (or FIFO), no partial writes will be 
permitted. Thus, the write will fail if a write of nbytt bytes would 
exceed a limit. 

If the file being written is a pipe (or FIFO) and the OJ>IDELAY flag 
of the file flag word is set, then write to a full pipe (or FIFO) will 
return a count of 0. Otherwise (OJ«JDELAY clear), writes to a full 
pipe (or FIFO) will block until space becomes available. 



Return Value 

Upon successful completion the number of bytes actually written is 
returned. Otherwise, - 1 is returned and errno is set to indicate the 
error. 



See Also 

creat(S), dup(S), Iseek(S), open(S), pipe(S), ulimit(S) 



Notes 



Writing a region of a file locked with locking causes write to hang 
indefinitely until the locked region is unlocked. 
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Diagnostics 

Xliet returns -1 and sets all type entries to zero if the file cannot be 
read, is not an object file, or contains an invalid name list. Other* 
wise, xlitt returns zero. A return value of zero does not indicate that 
any or all of the given symbols were found. 
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Name 

intro - Introduction to file formats. 

Description 

This section outlines the formats of various files. Usually, these 
structures can be found in the directories /usr/include or 
/usr/include/sys. 
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Name 

acct - Format of per-process accounting file. 

Description 

Files produced as a result of calling acef(S) have records in the form 
defined by <sys/acct.h>. 

In ae^fiag, the AFORK flag is turned on by each fork(S) and turned 
off by an ezee(S). The acjtomm field is inherited from the parent 
process and is reset by any txtc. Each time the system charges the 
process with a clock tick, it also adds the current process size to 
acjmtm computed as follows: 

(data size) + (text size) / (number of in-core processes using 
text) 

The value of acjmtm /ac_tttme can be viewed as an approximation to 
the mean process size, as modified by text-sharing. 

See Also 

acct(C), acctcom(C), acct(S) 



Notes 



The aejmetn value for a short-lived command gives little information 
about the actual size of the command, because acjmem may be 
incremented while a different command (e.g., the shell) is being exe- 
cuted by the process. 
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Name 

checklist - List of file systems processed by fsek. 



Description 

The /etc /checklist file contains a list of the file systems to be checked 
when fsek(C) is invoked without arguments. The list contains at 
most 15 special file names. Each special file name must be on a 
separate line and must correspond to a file system. 



See Also 

fsck(C) 
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Name 

cpio - Format of cpio archive. 

Description 

The header structure, when the c option is not used, is: 

struct { 

short hjmagic, 

h_dev, 

h_ino, 

h_mode, 

h_uid, 

h_gid, 

h_nlink, 

h_rdev, 

h_mtime[2], 

h_namesize, 

h_filesize[2]; 
char h_name[h_namesize rounded to word]; 
}Hdr; 

When the c option is used, the header information is described by 
the statement below: 

sscanf(Chdr,"%6o9SBo%6o%6o%6o%6o%6o%Bo%l llo%6o%Bo%s\ 
&Hdr.h_magic,&Hdr.h_dev,&Hdr.h_ino,&Hdr.h_mode, 
&Hdr.h_uid,&Hdr.h_^id,&Hdr.h_nlink,&Hdr.h_rdev, 
&Longtime,&Hdr.h_namesize,&Longfile,Hdr.h_name); 

Longtime and Long file are equivalent to Hir.hjmtime and 
Hdr.h_fileeize, respectively. The contents of each file is recorded in 
an element of the array of varying length structures, archive, 
together with other items describing the file. Every instance of 
hjmagie contains the constant 070707 (octal). The items h_jiev 
through h_mtime have meanings explained in itat(S). The length of 
the null- terminated pathname h_name, including the null byte, is 
given by hjnameeize. 

The last record of the archive always contains the name TRAILER!!!. 
Special files, directories, and the trailer are recorded with h_f&e$ize 
equal to zero. 

See Also 

cpio(C), find(C), stat(S) 
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Name 

dump - Incremental dump tape format 

Description 

The dump and rttstor commands are used to write and read incre- 
mental dump magnetic tapes. 

The dump tape consists of a header record, some bit mask records, a 
group of records describing file system directories, a group of records 
describing file system files, and some records describing a second bit 
mask. 

The header record and the first record of each description have the 
format described by the structure included by: 

^include <dumprestor.h> 

Fields in the dumpreetor structure are described below. 

NTREC is the number of 512 byte blocks in a physical tape record. 
MLEN is the number of bits in a bit map word. MSIZ is the number 
of bit map words. 

The TS_ entries are used in the cjtypt field to indicate what sort of 
header this is. The types and their meanings are as follows: 

TSJTYPE Tape volume label. 

TSJNODE A file or directory follows. The ejlinode field is a copy 
of the disk inode and contains bits telling what sort of 
file this is. 

TS_BITS A bit mask follows. This bit mask has a one bit for 

each inode that was dumped. 

TS.j\.DDR A subblock to a file {TSJNODE). See the description 
of c_eount below. 

TS_END End of tape record. 

TSjCLRI A bit mask follows. This bit mask contains a one bit 

for all inodes that were empty on the file system when 
dumped. 

MAGIC All header blocks have this number in cjmagie. 

CHECKSUM Header blocks checksum to this value. 
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Name 

file system - Format of a system volume. 



Syntax 



^include <sys/filsys.h> 
^include <sys /types .h> 
^include <sys/param.h> 



Description 

Every file system storage volume (e.g., a hard disk) has a common 
format for certain vital information. Every such volume is divided 
into a certain number of 256 word (512 byte) blocks. Block is 
unused and is available to contain a bootstrap program or other 
information. 

Block 1 is the $uper-bloek. The format of a super-block is described 
in /usr/include/sys/filesys.h. In that include file, Sjieizc is the 
address of the first data block after the i-list. The i-list starts just 
after the super-block in block 2; thus the i-list is $_itize- 2 blocks 
long. S_feize is the first block not potentially available for allocation 
to a file. These numbers are used by the system to check for bad 
block numbers. If an "impossible" block number is allocated from 
the free list or is freed, a diagnostic is written on the console. More- 
over, the free array is cleared so as to prevent further allocation 
from a presumably corrupted free list. 

The free list for each volume is maintained as follows. The »_/ree 
array contains, in »_/ree[l], ..., e_free[$_nfree- 1], up to 49 numbers 
of free blocks. S_free\0\ is the block number of the head of a chain 
of blocks constituting the free list. The first long in each free-chain 
block is the number (up to 50) of free-block numbers listed in the 
next 50 longs of this chain member. The first of these 50 blocks is 
the link to the next member of the chain. To allocate a block: decre- 
ment ejnfree, and the new block is t_free[t_nfree\. If the new block 
number is 0, there are no blocks left, so give an error. If $_nfree 
becomes 0, read in the block named by the new block number, 
replace t_nfrec by its first word, and copy the block numbers in the 
next 50 longs into the e_free array. To free a block, check if $_nfnc 
is 50; if so, copy $_nfree and the e_free array into it, write it out, and 
set e_nfree to 0. In any event set $_free\$_nfree] to the freed block's 
number and increment »_n/ree. 

Sjtfret is the total free blocks available in the file system. 

S_ninode is the number of free i-numbers in the tjinode array. To 
allocate an inode: if t_ninode is greater than 0, decrement it and 
return t_inode[e_ninode]. If it was 0, read the i-list and place the 
numbers of all free inodes (up to 100) into the $_inode array, then 

March 24, 1984 Page 1 



1 NODE (F) I NODE (T) 

Name 

inode - Format of an inode. 



Syntax 



#include <sys /types. h> 
^include <sys/ino.h> 



Description 

An inode for a plain file or directory in a file system has the struc- 
ture defined by <sys/ino.h>. For the meaning of the defined 
types off_t and timeJL see type${F). 



Files 

/usr/include/sys/ino.h 

See Also 

stat(S), filesystem(F), types(F) 
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MASTER (F) 



Part 2 contains lines with 11 fields each. Each field is a maximum of 
8 characters delimited by a blank if less than 8: 

Field 1: 

Device associated with this line 
Field 2: 

open routine 
Field 3: 

close routine 
Field 4: 

read routine 
Field 5: 

write routine 
Field 6: 

ioctl routine 
Field 7: 

receiver interupt routine 
Field 8: 

unused- should be nulldev 
Field 9: 

unused- should be nulldev 
Field 10: 

output start routine 
Field 11: 

unused- should be nulldev 

Part 3 contains lines, with 2 fields each: 

Field 1: alias name of device (8 chars, maximum). 

Field 2: reference name of device (8 chars, maximum; 

specified in part 1). 

Part 4 contains lines with 2 or 3 fields each: 

Field 1: parameter name (as it appears in description file; 

20 chars, maximum) 
Field 2: parameter name (as it appears in the c.c file; 20 

chars, maximum) 
Field 3: default parameter value (20 chars, maximum; 

parameter specification is required if this field is 

omitted) 

Devices that are not interrupt-driven have an interrupt vector sue of 
zero. Devices which generate interupts but are not of the standard 
character or block device mold, should be specified with a type (field 
4 in part 1) which has neither the block nor char bits set 



See Also 

config(CP) 
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Name 

sccsfile - Format of an SCCS file. 



Description 

An SCCS file is an ASCII file. It consists of six logical parts: the 
checksum, the delta tabic (contains information about each delta), 
user name* (contains login names and/or numerical group IDs of 
users who may add deltas), flags (contains definitions of internal 
keywords), comments (contains arbitrary descriptive information 
about the file), and the body (contains the actual text lines inter- 
mixed with control lines). Each logical part of an SCCS file is 
described in detail below. 

Throughout an SCCS file there are lines which begin with the ASCII 
SOH (start of heading) character (octal 001). This character is 
hereafter referred to as the control character and will be represented 
graphically as @ . Any line described below which is not depicted as 
beginning with the control character is prevented from beginning 
with the control character. Entries of the form DDDDD represent a 
five digit string (a number between 00000 and 99999). 

Checksum 

The checksum is the first line of an SCCS file. The form of the line 
is: 

©hDDDDD 

The value of the checksum is the sum of all characters, except those 
of the first line. The @ hR provides a magic number of (octal) 
064001. 

"Delta Table" 

The delta table consists of a variable number of entries of the form: 

@ 8 DDDDD/DDDDD/DDDDD 

@d <type> <SOCSID> yr/mo/da hr:mi:se <pgmr> DDDDD DDDDD 

@ i DDDDD ... 

@ x DDDDD... 

© g DDDDD ... 

@ m <MR number> 



ic < comments > ... 
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validity checking program. The i flag controls the warning/error 
aspect of the "No id keywords" message. When the i flag is not 
present, this message is only a warning; when the i flag is present, 
this message will cause a "fatal" error (the file will not be gotten, or 
the delta will not be made). When the b flag is present the — b 
option may be used with the get command to cause a branch in the 
delta tree. The m flag defines the first choice for the replacement 
text of the sccsfile.F identification keyword. The f flag defines the 
"floor" release; the release below which no deltas may be added. 
The c flag defines the "ceiling" release; the release above which no 
deltas may be added. The d flag defines the default SID to be used 
when none is specified on a get command. The n flag causes delta to 
insert a "null" delta (a delta that applies no changes) in those 
releases that are skipped when a delta is made in a new release (e.g., 
when delta 5.1 is made after delta 2.7, releases 3 and 4 are skipped). 
The absence of the n flag causes skipped releases to be completely 
empty. The j flag causes get to allow concurrent edits of the same 
base SID. The 1 flag defines a list of releases that are locked against 
editing (get(GP) with the -e option). The q flag defines the 
replacement for the identification keyword. 



Comment* 

Arbitrary text surrounded by the bracketing lines @ t and & T. The 
comments section typically contains a description of the file's pur- 
pose. 



Body 

The body consists of text lines and control lines. Text lines don't 
begin with the control character, control lines do. There are three 
kinds of control lines: in$ert, delete, and end, as follows: 

@I DDDDD 
@D DDDDD 
@EDDDDD 

The digit string (DDDDD) is the serial number corresponding to the 
delta for the control line. 



See Also 

admin(CP), delta(CP), get(CP), prs(CP) 
XsxiixProgrammer'$ Guide 
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Name 

x.out - loader output 

Synopsis 

#include [a.out.h] 

Description 

x.out is the output file of the loader M(CP). ld(CP) makes x.out 
executable if there are no errors and no unresolved external refer- 
ences. The following layout information is given in the include file 
for the 68000: 

struct xexec { /* x.out header */ 

unsigned short x_magic; /* magic number */ 
unsigned short xjext; /* size of header extension */ 



long 


xJext; 


/* size of text segment */ 


long 


xjdata; 


f* size of initialized data */ 


long 


xJbss; 


/♦size of uninitialized data */ 


long 


x-syms; 


/* size of symbol table */ 


long 


xj-eloc; 


f* relocation table length */ 


long 


xjentry; 


/* entry point */ 


char 


xxpu; 


/* cpu type & byte/word order */ 


char 


x-relsym; /* relocation & symbol format */ 


unsigned short x_renv; /* run— time environment */ 


struct 


xext{ 


/* x.out header extension */ 


long 


xeJrsize; 


1* size of text relocation */ 


long 


xejdrsize; 


/* size of data relocation */ 


long 


xejtbase; 


/* text relocation base */ 


long 


xejdbase; 


/* data relocation base */ 


long 


xejstksize; 


/* stack size (if XE-FS set) */ 



The file has four sections: a header, the program's text and data, 
relocation information, and a symbol table, in that order. The 
header optionally has a header extension as shown above. The 
relocation and symbol section will be empty if the program was 
loaded with the -s option of Id, or if the symbols and relocation 
have been removed by strip(CP). The sizes of each section in the 
header are given as longs, but have even alignment. The size of 
the header is not included in any of the other sizes. When an 
x.out file is loaded into core for execution, three logical segments 
are set up: the text segment, the data segment (with uninitialized 
data, which starts off as all 0, following initialized data), and a 
stack. The text segment begins at in the core image; the header 
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